diff --git a/404.html b/404.html index 46acebc47f..6f13fedbcb 100644 --- a/404.html +++ b/404.html @@ -7,14 +7,14 @@ Page Not Found | Hydra - +
Skip to main content

Page Not Found

We could not find what you were looking for.

Please contact the owner of the site that linked you to the original URL and let them know their link is broken.

- + \ No newline at end of file diff --git a/assets/js/0169dbe1.49fd705b.js b/assets/js/0169dbe1.49fd705b.js deleted file mode 100644 index 145fa9b7c1..0000000000 --- a/assets/js/0169dbe1.49fd705b.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[421],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>s,MDXProvider:()=>m,mdx:()=>f,useMDXComponents:()=>u,withMDXComponents:()=>c});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var s=r.createContext({}),c=function(e){return function(t){var n=u(t.components);return r.createElement(e,a({},t,{components:n}))}},u=function(e){var t=r.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},m=function(e){var t=u(e.components);return r.createElement(s.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},p=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,s=g(e,["components","mdxType","originalType","parentName"]),c=u(n),m=o,p=c["".concat(i,".").concat(m)]||c[m]||d[m]||a;return n?r.createElement(p,l(l({ref:t},s),{},{components:n})):r.createElement(p,l({ref:t},s))}));function f(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=n.length,i=new Array(a);i[0]=p;var l={};for(var g in t)hasOwnProperty.call(t,g)&&(l[g]=t[g]);l.originalType=e,l.mdxType="string"==typeof e?e:o,i[1]=l;for(var s=2;s{n.d(t,{A:()=>g,C:()=>s});var r=n(58168),o=n(96540),a=n(75489),i=n(44586),l=n(74098);function g(e){return o.createElement(a.default,(0,r.A)({},e,{to:(t=e.to,g=(0,l.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==g?void 0:g.name)?n:"current"]+t),target:"_blank"}));var t,n,g}function s(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return o.createElement(g,e,o.createElement("span",null,"\xa0"),o.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},96576:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>s,default:()=>d,frontMatter:()=>g,metadata:()=>c,toc:()=>u});var r=n(58168),o=n(98587),a=(n(96540),n(15680)),i=n(49595),l=["components"],g={id:"logging",title:"Customizing logging",sidebar_label:"Customizing logging"},s=void 0,c={unversionedId:"configure_hydra/logging",id:"version-1.2/configure_hydra/logging",title:"Customizing logging",description:"Hydra is configuring Python standard logging library with the dictConfig method. You can learn more about it here.",source:"@site/versioned_docs/version-1.2/configure_hydra/logging.md",sourceDirName:"configure_hydra",slug:"/configure_hydra/logging",permalink:"/docs/1.2/configure_hydra/logging",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/configure_hydra/logging.md",tags:[],version:"1.2",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"logging",title:"Customizing logging",sidebar_label:"Customizing logging"},sidebar:"docs",previous:{title:"Job Configuration",permalink:"/docs/1.2/configure_hydra/job"},next:{title:"Customizing working directory pattern",permalink:"/docs/1.2/configure_hydra/workdir"}},u=[],m={toc:u};function d(e){var t=e.components,n=(0,o.A)(e,l);return(0,a.mdx)("wrapper",(0,r.A)({},m,n,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)(i.C,{text:"Example application",to:"examples/configure_hydra/logging",mdxType:"ExampleGithubLink"}),(0,a.mdx)("p",null,"Hydra is configuring Python standard logging library with the dictConfig method. You can learn more about it ",(0,a.mdx)("a",{parentName:"p",href:"https://docs.python.org/3/howto/logging.html"},"here"),".\nThere are two logging configurations, one for Hydra itself and one for the executed jobs."),(0,a.mdx)("p",null,"This example demonstrates how to customize the logging behavior of your Hydra app, by making the following changes\nto the default logging behavior:"),(0,a.mdx)("ul",null,(0,a.mdx)("li",{parentName:"ul"},"Outputs only to stdout (no log file)"),(0,a.mdx)("li",{parentName:"ul"},"Output a simpler log line pattern")),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - override hydra/job_logging: custom\n")),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="hydra/job_logging/custom.yaml"',title:'"hydra/job_logging/custom.yaml"'},"version: 1\nformatters:\n simple:\n format: '[%(levelname)s] - %(message)s'\nhandlers:\n console:\n class: logging.StreamHandler\n formatter: simple\n stream: ext://sys.stdout\nroot:\n handlers: [console]\n\ndisable_existing_loggers: false\n")),(0,a.mdx)("p",null,"This is what the default logging looks like:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre"},"$ python my_app.py hydra/job_logging=default\n[2020-08-24 13:43:26,761][__main__][INFO] - Info level message\n")),(0,a.mdx)("p",null,"And this is what the custom logging looks like:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text"},"$ python my_app.py \n[INFO] - Info level message\n")))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/0169dbe1.d1d1b8fd.js b/assets/js/0169dbe1.d1d1b8fd.js new file mode 100644 index 0000000000..46d02132bf --- /dev/null +++ b/assets/js/0169dbe1.d1d1b8fd.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[421],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>s,MDXProvider:()=>m,mdx:()=>f,useMDXComponents:()=>u,withMDXComponents:()=>c});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var s=r.createContext({}),c=function(e){return function(t){var n=u(t.components);return r.createElement(e,a({},t,{components:n}))}},u=function(e){var t=r.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},m=function(e){var t=u(e.components);return r.createElement(s.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},p=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,s=g(e,["components","mdxType","originalType","parentName"]),c=u(n),m=o,p=c["".concat(i,".").concat(m)]||c[m]||d[m]||a;return n?r.createElement(p,l(l({ref:t},s),{},{components:n})):r.createElement(p,l({ref:t},s))}));function f(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=n.length,i=new Array(a);i[0]=p;var l={};for(var g in t)hasOwnProperty.call(t,g)&&(l[g]=t[g]);l.originalType=e,l.mdxType="string"==typeof e?e:o,i[1]=l;for(var s=2;s{n.d(t,{A:()=>g,C:()=>s});var r=n(58168),o=n(96540),a=n(75489),i=n(44586),l=n(74098);function g(e){return o.createElement(a.default,(0,r.A)({},e,{to:(t=e.to,g=(0,l.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==g?void 0:g.name)?n:"current"]+t),target:"_blank"}));var t,n,g}function s(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return o.createElement(g,e,o.createElement("span",null,"\xa0"),o.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},96576:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>s,default:()=>d,frontMatter:()=>g,metadata:()=>c,toc:()=>u});var r=n(58168),o=n(98587),a=(n(96540),n(15680)),i=n(49595),l=["components"],g={id:"logging",title:"Customizing logging",sidebar_label:"Customizing logging"},s=void 0,c={unversionedId:"configure_hydra/logging",id:"version-1.2/configure_hydra/logging",title:"Customizing logging",description:"Hydra is configuring Python standard logging library with the dictConfig method. You can learn more about it here.",source:"@site/versioned_docs/version-1.2/configure_hydra/logging.md",sourceDirName:"configure_hydra",slug:"/configure_hydra/logging",permalink:"/docs/1.2/configure_hydra/logging",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/configure_hydra/logging.md",tags:[],version:"1.2",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"logging",title:"Customizing logging",sidebar_label:"Customizing logging"},sidebar:"docs",previous:{title:"Job Configuration",permalink:"/docs/1.2/configure_hydra/job"},next:{title:"Customizing working directory pattern",permalink:"/docs/1.2/configure_hydra/workdir"}},u=[],m={toc:u};function d(e){var t=e.components,n=(0,o.A)(e,l);return(0,a.mdx)("wrapper",(0,r.A)({},m,n,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)(i.C,{text:"Example application",to:"examples/configure_hydra/logging",mdxType:"ExampleGithubLink"}),(0,a.mdx)("p",null,"Hydra is configuring Python standard logging library with the dictConfig method. You can learn more about it ",(0,a.mdx)("a",{parentName:"p",href:"https://docs.python.org/3/howto/logging.html"},"here"),".\nThere are two logging configurations, one for Hydra itself and one for the executed jobs."),(0,a.mdx)("p",null,"This example demonstrates how to customize the logging behavior of your Hydra app, by making the following changes\nto the default logging behavior:"),(0,a.mdx)("ul",null,(0,a.mdx)("li",{parentName:"ul"},"Outputs only to stdout (no log file)"),(0,a.mdx)("li",{parentName:"ul"},"Output a simpler log line pattern")),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - override hydra/job_logging: custom\n")),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="hydra/job_logging/custom.yaml"',title:'"hydra/job_logging/custom.yaml"'},"version: 1\nformatters:\n simple:\n format: '[%(levelname)s] - %(message)s'\nhandlers:\n console:\n class: logging.StreamHandler\n formatter: simple\n stream: ext://sys.stdout\nroot:\n handlers: [console]\n\ndisable_existing_loggers: false\n")),(0,a.mdx)("p",null,"This is what the default logging looks like:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre"},"$ python my_app.py hydra/job_logging=default\n[2020-08-24 13:43:26,761][__main__][INFO] - Info level message\n")),(0,a.mdx)("p",null,"And this is what the custom logging looks like:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text"},"$ python my_app.py \n[INFO] - Info level message\n")))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/028aaae6.638ed263.js b/assets/js/028aaae6.638ed263.js deleted file mode 100644 index edb7e79152..0000000000 --- a/assets/js/028aaae6.638ed263.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3139],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>s,MDXProvider:()=>h,mdx:()=>f,useMDXComponents:()=>l,withMDXComponents:()=>p});var r=n(96540);function a(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(){return i=Object.assign||function(e){for(var t=1;t=0||(a[n]=e[n]);return a}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(a[n]=e[n])}return a}var s=r.createContext({}),p=function(e){return function(t){var n=l(t.components);return r.createElement(e,i({},t,{components:n}))}},l=function(e){var t=r.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):c(c({},t),e)),n},h=function(e){var t=l(e.components);return r.createElement(s.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},m=r.forwardRef((function(e,t){var n=e.components,a=e.mdxType,i=e.originalType,o=e.parentName,s=d(e,["components","mdxType","originalType","parentName"]),p=l(n),h=a,m=p["".concat(o,".").concat(h)]||p[h]||u[h]||i;return n?r.createElement(m,c(c({ref:t},s),{},{components:n})):r.createElement(m,c({ref:t},s))}));function f(e,t){var n=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var i=n.length,o=new Array(i);o[0]=m;var c={};for(var d in t)hasOwnProperty.call(t,d)&&(c[d]=t[d]);c.originalType=e,c.mdxType="string"==typeof e?e:a,o[1]=c;for(var s=2;s{n.r(t),n.d(t,{contentTitle:()=>d,default:()=>h,frontMatter:()=>c,metadata:()=>s,toc:()=>p});var r=n(58168),a=n(98587),i=(n(96540),n(15680)),o=["components"],c={id:"changes_to_hydra_main_config_path",title:"Changes to @hydra.main() and hydra.initialize()"},d=void 0,s={unversionedId:"upgrades/1.0_to_1.1/changes_to_hydra_main_config_path",id:"version-1.3/upgrades/1.0_to_1.1/changes_to_hydra_main_config_path",title:"Changes to @hydra.main() and hydra.initialize()",description:"Prior to Hydra 1.1, @hydra.main() and hydra.initialize() default config path was the directory containing the Python app (calling @hydra.main() or hydra.initialize()).",source:"@site/versioned_docs/version-1.3/upgrades/1.0_to_1.1/hydra_main_config_path.md",sourceDirName:"upgrades/1.0_to_1.1",slug:"/upgrades/1.0_to_1.1/changes_to_hydra_main_config_path",permalink:"/docs/1.3/upgrades/1.0_to_1.1/changes_to_hydra_main_config_path",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/upgrades/1.0_to_1.1/hydra_main_config_path.md",tags:[],version:"1.3",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"changes_to_hydra_main_config_path",title:"Changes to @hydra.main() and hydra.initialize()"},sidebar:"docs",previous:{title:"Changes to configuring sweeper's search space",permalink:"/docs/1.3/upgrades/1.1_to_1.2/changes_to_sweeper_config"},next:{title:"Changes to default composition order",permalink:"/docs/1.3/upgrades/1.0_to_1.1/default_composition_order"}},p=[{value:"Dedicated config directory",id:"dedicated-config-directory",children:[],level:3},{value:"No config directory",id:"no-config-directory",children:[],level:3},{value:"Using the application directory",id:"using-the-application-directory",children:[],level:3}],l={toc:p};function h(e){var t=e.components,n=(0,a.A)(e,o);return(0,i.mdx)("wrapper",(0,r.A)({},l,n,{components:t,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Prior to Hydra 1.1, ",(0,i.mdx)("strong",{parentName:"p"},"@hydra.main()")," and ",(0,i.mdx)("strong",{parentName:"p"},"hydra.initialize()")," default ",(0,i.mdx)("inlineCode",{parentName:"p"},"config path")," was the directory containing the Python app (calling ",(0,i.mdx)("strong",{parentName:"p"},"@hydra.main()")," or ",(0,i.mdx)("strong",{parentName:"p"},"hydra.initialize()"),")."),(0,i.mdx)("p",null,"This can cause unexpected behavior:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"Sibling directories are interpreted as config groups, which can lead to surprising results (See ",(0,i.mdx)("a",{parentName:"li",href:"https://github.com/facebookresearch/hydra/issues/1533"},"#1533"),")."),(0,i.mdx)("li",{parentName:"ul"},"The subtree added automatically can have many files/directories - which will cause ",(0,i.mdx)("strong",{parentName:"li"},"--help")," to be very slow as it's scanning for all config groups/config files (See ",(0,i.mdx)("a",{parentName:"li",href:"https://github.com/facebookresearch/hydra/issues/759"},"#759"),").")),(0,i.mdx)("p",null,"To address these issues, Hydra 1.1 issues a warning if the config_path is not specified.",(0,i.mdx)("br",{parentName:"p"}),"\n","Your options are as follows:"),(0,i.mdx)("h3",{id:"dedicated-config-directory"},"Dedicated config directory"),(0,i.mdx)("p",null,'For applications with config files, specify a directory like "conf" to use a dedicated config directory relative to the application.'),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python"},'@hydra.main(config_path="conf")\n# or:\nhydra.initialize(config_path="conf")\n')),(0,i.mdx)("h3",{id:"no-config-directory"},"No config directory"),(0,i.mdx)("p",null,"For applications that do not define config files next to the Python script (typically applications using only Structured Configs), it is recommended that\nyou pass ",(0,i.mdx)("inlineCode",{parentName:"p"},"None")," as the config_path, indicating that no directory should be added to the config search path.\nThis will become the default with ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.3/upgrades/version_base"},"version_base"),' >= "1.2"'),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python"},"@hydra.main(config_path=None)\n# or:\nhydra.initialize(config_path=None)\n")),(0,i.mdx)("h3",{id:"using-the-application-directory"},"Using the application directory"),(0,i.mdx)("p",null,"Use the directory/module of the Python script.\nThis was the default behavior up to Hydra 1.0.",(0,i.mdx)("br",{parentName:"p"}),"\n","This is not recommended as it can cause the surprising behavior outlined above."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python"},'@hydra.main(config_path=".")\n# or:\nhydra.initialize(config_path=".")\n')))}h.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/028aaae6.d1c9ce36.js b/assets/js/028aaae6.d1c9ce36.js new file mode 100644 index 0000000000..1068ccf6a3 --- /dev/null +++ b/assets/js/028aaae6.d1c9ce36.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3139],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>s,MDXProvider:()=>h,mdx:()=>f,useMDXComponents:()=>l,withMDXComponents:()=>p});var r=n(96540);function a(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(){return i=Object.assign||function(e){for(var t=1;t=0||(a[n]=e[n]);return a}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(a[n]=e[n])}return a}var s=r.createContext({}),p=function(e){return function(t){var n=l(t.components);return r.createElement(e,i({},t,{components:n}))}},l=function(e){var t=r.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):c(c({},t),e)),n},h=function(e){var t=l(e.components);return r.createElement(s.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},m=r.forwardRef((function(e,t){var n=e.components,a=e.mdxType,i=e.originalType,o=e.parentName,s=d(e,["components","mdxType","originalType","parentName"]),p=l(n),h=a,m=p["".concat(o,".").concat(h)]||p[h]||u[h]||i;return n?r.createElement(m,c(c({ref:t},s),{},{components:n})):r.createElement(m,c({ref:t},s))}));function f(e,t){var n=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var i=n.length,o=new Array(i);o[0]=m;var c={};for(var d in t)hasOwnProperty.call(t,d)&&(c[d]=t[d]);c.originalType=e,c.mdxType="string"==typeof e?e:a,o[1]=c;for(var s=2;s{n.r(t),n.d(t,{contentTitle:()=>d,default:()=>h,frontMatter:()=>c,metadata:()=>s,toc:()=>p});var r=n(58168),a=n(98587),i=(n(96540),n(15680)),o=["components"],c={id:"changes_to_hydra_main_config_path",title:"Changes to @hydra.main() and hydra.initialize()"},d=void 0,s={unversionedId:"upgrades/1.0_to_1.1/changes_to_hydra_main_config_path",id:"version-1.3/upgrades/1.0_to_1.1/changes_to_hydra_main_config_path",title:"Changes to @hydra.main() and hydra.initialize()",description:"Prior to Hydra 1.1, @hydra.main() and hydra.initialize() default config path was the directory containing the Python app (calling @hydra.main() or hydra.initialize()).",source:"@site/versioned_docs/version-1.3/upgrades/1.0_to_1.1/hydra_main_config_path.md",sourceDirName:"upgrades/1.0_to_1.1",slug:"/upgrades/1.0_to_1.1/changes_to_hydra_main_config_path",permalink:"/docs/1.3/upgrades/1.0_to_1.1/changes_to_hydra_main_config_path",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/upgrades/1.0_to_1.1/hydra_main_config_path.md",tags:[],version:"1.3",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"changes_to_hydra_main_config_path",title:"Changes to @hydra.main() and hydra.initialize()"},sidebar:"docs",previous:{title:"Changes to configuring sweeper's search space",permalink:"/docs/1.3/upgrades/1.1_to_1.2/changes_to_sweeper_config"},next:{title:"Changes to default composition order",permalink:"/docs/1.3/upgrades/1.0_to_1.1/default_composition_order"}},p=[{value:"Dedicated config directory",id:"dedicated-config-directory",children:[],level:3},{value:"No config directory",id:"no-config-directory",children:[],level:3},{value:"Using the application directory",id:"using-the-application-directory",children:[],level:3}],l={toc:p};function h(e){var t=e.components,n=(0,a.A)(e,o);return(0,i.mdx)("wrapper",(0,r.A)({},l,n,{components:t,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Prior to Hydra 1.1, ",(0,i.mdx)("strong",{parentName:"p"},"@hydra.main()")," and ",(0,i.mdx)("strong",{parentName:"p"},"hydra.initialize()")," default ",(0,i.mdx)("inlineCode",{parentName:"p"},"config path")," was the directory containing the Python app (calling ",(0,i.mdx)("strong",{parentName:"p"},"@hydra.main()")," or ",(0,i.mdx)("strong",{parentName:"p"},"hydra.initialize()"),")."),(0,i.mdx)("p",null,"This can cause unexpected behavior:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"Sibling directories are interpreted as config groups, which can lead to surprising results (See ",(0,i.mdx)("a",{parentName:"li",href:"https://github.com/facebookresearch/hydra/issues/1533"},"#1533"),")."),(0,i.mdx)("li",{parentName:"ul"},"The subtree added automatically can have many files/directories - which will cause ",(0,i.mdx)("strong",{parentName:"li"},"--help")," to be very slow as it's scanning for all config groups/config files (See ",(0,i.mdx)("a",{parentName:"li",href:"https://github.com/facebookresearch/hydra/issues/759"},"#759"),").")),(0,i.mdx)("p",null,"To address these issues, Hydra 1.1 issues a warning if the config_path is not specified.",(0,i.mdx)("br",{parentName:"p"}),"\n","Your options are as follows:"),(0,i.mdx)("h3",{id:"dedicated-config-directory"},"Dedicated config directory"),(0,i.mdx)("p",null,'For applications with config files, specify a directory like "conf" to use a dedicated config directory relative to the application.'),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python"},'@hydra.main(config_path="conf")\n# or:\nhydra.initialize(config_path="conf")\n')),(0,i.mdx)("h3",{id:"no-config-directory"},"No config directory"),(0,i.mdx)("p",null,"For applications that do not define config files next to the Python script (typically applications using only Structured Configs), it is recommended that\nyou pass ",(0,i.mdx)("inlineCode",{parentName:"p"},"None")," as the config_path, indicating that no directory should be added to the config search path.\nThis will become the default with ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.3/upgrades/version_base"},"version_base"),' >= "1.2"'),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python"},"@hydra.main(config_path=None)\n# or:\nhydra.initialize(config_path=None)\n")),(0,i.mdx)("h3",{id:"using-the-application-directory"},"Using the application directory"),(0,i.mdx)("p",null,"Use the directory/module of the Python script.\nThis was the default behavior up to Hydra 1.0.",(0,i.mdx)("br",{parentName:"p"}),"\n","This is not recommended as it can cause the surprising behavior outlined above."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python"},'@hydra.main(config_path=".")\n# or:\nhydra.initialize(config_path=".")\n')))}h.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/02deea7a.6654644c.js b/assets/js/02deea7a.6654644c.js deleted file mode 100644 index d9bbe151d3..0000000000 --- a/assets/js/02deea7a.6654644c.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[9634],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>d,MDXProvider:()=>c,mdx:()=>f,useMDXComponents:()=>p,withMDXComponents:()=>m});var a=n(96540);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function r(){return r=Object.assign||function(e){for(var t=1;t=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var d=a.createContext({}),m=function(e){return function(t){var n=p(t.components);return a.createElement(e,r({},t,{components:n}))}},p=function(e){var t=a.useContext(d),n=t;return e&&(n="function"==typeof e?e(t):s(s({},t),e)),n},c=function(e){var t=p(e.components);return a.createElement(d.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},g=a.forwardRef((function(e,t){var n=e.components,i=e.mdxType,r=e.originalType,o=e.parentName,d=l(e,["components","mdxType","originalType","parentName"]),m=p(n),c=i,g=m["".concat(o,".").concat(c)]||m[c]||u[c]||r;return n?a.createElement(g,s(s({ref:t},d),{},{components:n})):a.createElement(g,s({ref:t},d))}));function f(e,t){var n=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var r=n.length,o=new Array(r);o[0]=g;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s.mdxType="string"==typeof e?e:i,o[1]=s;for(var d=2;d{n.d(t,{A:()=>l,C:()=>d});var a=n(58168),i=n(96540),r=n(75489),o=n(44586),s=n(74098);function l(e){return i.createElement(r.default,(0,a.A)({},e,{to:(t=e.to,l=(0,s.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==l?void 0:l.name)?n:"current"]+t),target:"_blank"}));var t,n,l}function d(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return i.createElement(l,e,i.createElement("span",null,"\xa0"),i.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},63594:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>m,default:()=>f,frontMatter:()=>d,metadata:()=>p,toc:()=>c});var a,i=n(58168),r=n(98587),o=(n(96540),n(15680)),s=n(49595),l=["components"],d={id:"overview",title:"Instantiating objects with Hydra",sidebar_label:"Overview"},m=void 0,p={unversionedId:"advanced/instantiate_objects/overview",id:"version-1.3/advanced/instantiate_objects/overview",title:"Instantiating objects with Hydra",description:"One of the best ways to drive different behavior in an application is to instantiate different implementations of an interface.",source:"@site/versioned_docs/version-1.3/advanced/instantiate_objects/overview.md",sourceDirName:"advanced/instantiate_objects",slug:"/advanced/instantiate_objects/overview",permalink:"/docs/1.3/advanced/instantiate_objects/overview",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/advanced/instantiate_objects/overview.md",tags:[],version:"1.3",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"overview",title:"Instantiating objects with Hydra",sidebar_label:"Overview"},sidebar:"docs",previous:{title:"Packages",permalink:"/docs/1.3/advanced/overriding_packages"},next:{title:"Config files example",permalink:"/docs/1.3/advanced/instantiate_objects/config_files"}},c=[{value:"Simple usage",id:"simple-usage",children:[],level:3},{value:"Recursive instantiation",id:"recursive-instantiation",children:[],level:3},{value:"Disable recursive instantiation",id:"disable-recursive-instantiation",children:[],level:3},{value:"Parameter conversion strategies",id:"parameter-conversion-strategies",children:[],level:3},{value:"Partial Instantiation",id:"partial-instantiation",children:[],level:3},{value:"Instantiation of builtins",id:"instantiation-of-builtins",children:[],level:3},{value:"Dotpath lookup machinery",id:"dotpath-lookup-machinery",children:[],level:3}],u=(a="GithubLink",function(e){return console.warn("Component "+a+" was not imported, exported, or provided by MDXProvider as global scope"),(0,o.mdx)("div",e)}),g={toc:c};function f(e){var t=e.components,n=(0,r.A)(e,l);return(0,o.mdx)("wrapper",(0,i.A)({},g,n,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)(s.C,{text:"Example applications",to:"examples/instantiate",mdxType:"ExampleGithubLink"}),(0,o.mdx)("p",null,"One of the best ways to drive different behavior in an application is to instantiate different implementations of an interface.\nThe code using the instantiated object only knows the interface which remains constant, but the behavior\nis determined by the actual object instance."),(0,o.mdx)("p",null,"Hydra provides ",(0,o.mdx)("inlineCode",{parentName:"p"},"hydra.utils.instantiate()")," (and its alias ",(0,o.mdx)("inlineCode",{parentName:"p"},"hydra.utils.call()"),") for instantiating objects and calling functions. Prefer ",(0,o.mdx)("inlineCode",{parentName:"p"},"instantiate")," for creating objects and ",(0,o.mdx)("inlineCode",{parentName:"p"},"call")," for invoking functions."),(0,o.mdx)("p",null,"Call/instantiate supports:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"Constructing an object by calling the ",(0,o.mdx)("inlineCode",{parentName:"li"},"__init__")," method"),(0,o.mdx)("li",{parentName:"ul"},"Calling functions, static functions, class methods and other callable global objects")),(0,o.mdx)("details",null,(0,o.mdx)("summary",null,"Instantiate API (Expand for details)"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'def instantiate(config: Any, *args: Any, **kwargs: Any) -> Any:\n """\n :param config: An config object describing what to call and what params to use.\n In addition to the parameters, the config must contain:\n _target_ : target class or callable name (str)\n And may contain:\n _args_: List-like of positional arguments to pass to the target\n _recursive_: Construct nested objects as well (bool).\n True by default.\n may be overridden via a _recursive_ key in\n the kwargs\n _convert_: Conversion strategy\n none : Passed objects are DictConfig and ListConfig, default\n partial : Passed objects are converted to dict and list, with\n the exception of Structured Configs (and their fields).\n object : Passed objects are converted to dict and list.\n Structured Configs are converted to instances of the\n backing dataclass / attr class.\n all : Passed objects are dicts, lists and primitives without\n a trace of OmegaConf containers. Structured configs\n are converted to dicts / lists too.\n _partial_: If True, return functools.partial wrapped method or object\n False by default. Configure per target.\n :param args: Optional positional parameters pass-through\n :param kwargs: Optional named parameters to override\n parameters in the config object. Parameters not present\n in the config objects are being passed as is to the target.\n IMPORTANT: dataclasses instances in kwargs are interpreted as config\n and cannot be used as passthrough\n :return: if _target_ is a class name: the instantiated object\n if _target_ is a callable: the return value of the call\n """\n\n# Alias for instantiate\ncall = instantiate\n'))),(0,o.mdx)("br",null),(0,o.mdx)("p",null,"The config passed to these functions must have a key called ",(0,o.mdx)("inlineCode",{parentName:"p"},"_target_"),", with the value of a fully qualified class name, class method, static method or callable.\nFor convenience, ",(0,o.mdx)("inlineCode",{parentName:"p"},"None")," config results in a ",(0,o.mdx)("inlineCode",{parentName:"p"},"None")," object."),(0,o.mdx)("p",null,(0,o.mdx)("strong",{parentName:"p"},"Named arguments")," : Config fields (except reserved fields like ",(0,o.mdx)("inlineCode",{parentName:"p"},"_target_"),") are passed as named arguments to the target.\nNamed arguments in the config can be overridden by passing named argument with the same name in the ",(0,o.mdx)("inlineCode",{parentName:"p"},"instantiate()")," call-site."),(0,o.mdx)("p",null,(0,o.mdx)("strong",{parentName:"p"},"Positional arguments")," : The config may contain a ",(0,o.mdx)("inlineCode",{parentName:"p"},"_args_")," field representing positional arguments to pass to the target.\nThe positional arguments can be overridden together by passing positional arguments in the ",(0,o.mdx)("inlineCode",{parentName:"p"},"instantiate()")," call-site."),(0,o.mdx)("h3",{id:"simple-usage"},"Simple usage"),(0,o.mdx)("p",null,"Your application might have an Optimizer class:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Example class"',title:'"Example','class"':!0},"class Optimizer:\n algo: str\n lr: float\n\n def __init__(self, algo: str, lr: float) -> None:\n self.algo = algo\n self.lr = lr\n")),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Config"',title:'"Config"'},"optimizer:\n _target_: my_app.Optimizer\n algo: SGD\n lr: 0.01\n\n\n\n\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Instantiation"',title:'"Instantiation"'},"opt = instantiate(cfg.optimizer)\nprint(opt)\n# Optimizer(algo=SGD,lr=0.01)\n\n# override parameters on the call-site\nopt = instantiate(cfg.optimizer, lr=0.2)\nprint(opt)\n# Optimizer(algo=SGD,lr=0.2)\n")))),(0,o.mdx)("h3",{id:"recursive-instantiation"},"Recursive instantiation"),(0,o.mdx)("p",null,"Let's add a Dataset and a Trainer class. The trainer holds a Dataset and an Optimizer instances."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Additional classes"',title:'"Additional','classes"':!0},"class Dataset:\n name: str\n path: str\n\n def __init__(self, name: str, path: str) -> None:\n self.name = name\n self.path = path\n\n\nclass Trainer:\n def __init__(self, optimizer: Optimizer, dataset: Dataset) -> None:\n self.optimizer = optimizer\n self.dataset = dataset\n")),(0,o.mdx)("p",null,"With the following config, you can instantiate the whole thing with a single call:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Example config"',title:'"Example','config"':!0},"trainer:\n _target_: my_app.Trainer\n optimizer:\n _target_: my_app.Optimizer\n algo: SGD\n lr: 0.01\n dataset:\n _target_: my_app.Dataset\n name: Imagenet\n path: /datasets/imagenet\n")),(0,o.mdx)("p",null,"Hydra will instantiate nested objects recursively by default."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},"trainer = instantiate(cfg.trainer)\nprint(trainer)\n# Trainer(\n# optimizer=Optimizer(algo=SGD,lr=0.01),\n# dataset=Dataset(name=Imagenet, path=/datasets/imagenet)\n# )\n")),(0,o.mdx)("p",null,"You can override parameters for nested objects:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'trainer = instantiate(\n cfg.trainer,\n optimizer={"lr": 0.3},\n dataset={"name": "cifar10", "path": "/datasets/cifar10"},\n)\nprint(trainer)\n# Trainer(\n# optimizer=Optimizer(algo=SGD,lr=0.3),\n# dataset=Dataset(name=cifar10, path=/datasets/cifar10)\n# )\n')),(0,o.mdx)("p",null,"Similarly, positional arguments of nested objects can be overridden:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'obj = instantiate(\n cfg.object,\n # pass 1 and 2 as positional arguments to the target object\n 1, 2, \n # pass 3 and 4 as positional arguments to a nested child object\n child={"_args_": [3, 4]},\n)\n')),(0,o.mdx)("h3",{id:"disable-recursive-instantiation"},"Disable recursive instantiation"),(0,o.mdx)("p",null,"You can disable recursive instantiation by setting ",(0,o.mdx)("inlineCode",{parentName:"p"},"_recursive_")," to ",(0,o.mdx)("inlineCode",{parentName:"p"},"False")," in the config node or in the call-site\nIn that case the Trainer object will receive an OmegaConf DictConfig for nested dataset and optimizer instead of the instantiated objects."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},"optimizer = instantiate(cfg.trainer, _recursive_=False)\nprint(optimizer)\n")),(0,o.mdx)("p",null,"Output:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},"Trainer(\n optimizer={\n '_target_': 'my_app.Optimizer', 'algo': 'SGD', 'lr': 0.01\n },\n dataset={\n '_target_': 'my_app.Dataset', 'name': 'Imagenet', 'path': '/datasets/imagenet'\n }\n)\n")),(0,o.mdx)("h3",{id:"parameter-conversion-strategies"},"Parameter conversion strategies"),(0,o.mdx)("p",null,"By default, the parameters passed to the target are either primitives (int,\nfloat, bool etc) or OmegaConf containers (",(0,o.mdx)("inlineCode",{parentName:"p"},"DictConfig"),", ",(0,o.mdx)("inlineCode",{parentName:"p"},"ListConfig"),").\nOmegaConf containers have many advantages over primitive dicts and lists,\nincluding convenient attribute access for keys,\n",(0,o.mdx)("a",{parentName:"p",href:"https://omegaconf.readthedocs.io/en/latest/structured_config.html"},"duck-typing as instances of dataclasses or attrs classes"),", and\nsupport for ",(0,o.mdx)("a",{parentName:"p",href:"https://omegaconf.readthedocs.io/en/latest/usage.html#variable-interpolation"},"variable interpolation"),"\nand ",(0,o.mdx)("a",{parentName:"p",href:"https://omegaconf.readthedocs.io/en/latest/custom_resolvers.html"},"custom resolvers"),".\nIf the callable targeted by ",(0,o.mdx)("inlineCode",{parentName:"p"},"instantiate")," leverages OmegaConf's features, it\nwill make sense to pass ",(0,o.mdx)("inlineCode",{parentName:"p"},"DictConfig")," and ",(0,o.mdx)("inlineCode",{parentName:"p"},"ListConfig")," instances directly to\nthat callable."),(0,o.mdx)("p",null,"That being said, in many cases it's desired to pass normal Python dicts and\nlists, rather than ",(0,o.mdx)("inlineCode",{parentName:"p"},"DictConfig")," or ",(0,o.mdx)("inlineCode",{parentName:"p"},"ListConfig")," instances, as arguments to your\ncallable. You can change instantiate's argument conversion strategy using the\n",(0,o.mdx)("inlineCode",{parentName:"p"},"_convert_")," parameter. Supported values are:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},'"none"')," : Default behavior, Use OmegaConf containers"),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},'"partial"')," : Convert OmegaConf containers to dict and list, except\nStructured Configs, which remain as DictConfig instances."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},'"object"')," : Convert OmegaConf containers to dict and list, except Structured\nConfigs, which are converted to instances of the backing dataclass / attr\nclass using ",(0,o.mdx)("inlineCode",{parentName:"li"},"OmegaConf.to_object"),"."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},'"all"')," : Convert everything to primitive containers")),(0,o.mdx)("p",null,"The conversion strategy applies recursively to all subconfigs of the instantiation target.\nHere is an example demonstrating the various conversion strategies:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'from dataclasses import dataclass\nfrom omegaconf import DictConfig, OmegaConf\nfrom hydra.utils import instantiate\n\n@dataclass\nclass Foo:\n a: int = 123\n\nclass MyTarget:\n def __init__(self, foo, bar):\n self.foo = foo\n self.bar = bar\n\ncfg = OmegaConf.create(\n {\n "_target_": "__main__.MyTarget",\n "foo": Foo(),\n "bar": {"b": 456},\n }\n)\n\nobj_none = instantiate(cfg, _convert_="none")\nassert isinstance(obj_none, MyTarget)\nassert isinstance(obj_none.foo, DictConfig)\nassert isinstance(obj_none.bar, DictConfig)\n\nobj_partial = instantiate(cfg, _convert_="partial")\nassert isinstance(obj_partial, MyTarget)\nassert isinstance(obj_partial.foo, DictConfig)\nassert isinstance(obj_partial.bar, dict)\n\nobj_object = instantiate(cfg, _convert_="object")\nassert isinstance(obj_object, MyTarget)\nassert isinstance(obj_object.foo, Foo)\nassert isinstance(obj_object.bar, dict)\n\nobj_all = instantiate(cfg, _convert_="all")\nassert isinstance(obj_none, MyTarget)\nassert isinstance(obj_all.foo, dict)\nassert isinstance(obj_all.bar, dict)\n')),(0,o.mdx)("p",null,"Passing the ",(0,o.mdx)("inlineCode",{parentName:"p"},"_convert_")," keyword argument to ",(0,o.mdx)("inlineCode",{parentName:"p"},"instantiate")," has the same effect as defining\na ",(0,o.mdx)("inlineCode",{parentName:"p"},"_convert_")," attribute on your config object. Here is an example creating\ninstances of ",(0,o.mdx)("inlineCode",{parentName:"p"},"MyTarget")," that are equivalent to the above:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'cfg_none = OmegaConf.create({..., "_convert_": "none"})\nobj_none = instantiate(cfg_none)\n\ncfg_partial = OmegaConf.create({..., "_convert_": "partial"})\nobj_partial = instantiate(cfg_partial)\n\ncfg_object = OmegaConf.create({..., "_convert_": "object"})\nobj_object = instantiate(cfg_object)\n\ncfg_all = OmegaConf.create({..., "_convert_": "all"})\nobj_all = instantiate(cfg_all)\n')),(0,o.mdx)("h3",{id:"partial-instantiation"},"Partial Instantiation"),(0,o.mdx)("p",null,"Sometimes you may not set all parameters needed to instantiate an object from the configuration, in this case you can set\n",(0,o.mdx)("inlineCode",{parentName:"p"},"_partial_")," to be ",(0,o.mdx)("inlineCode",{parentName:"p"},"True")," to get a ",(0,o.mdx)("inlineCode",{parentName:"p"},"functools.partial")," wrapped object or method, then complete initializing the object in\nthe application code. Here is an example:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Example classes"',title:'"Example','classes"':!0},'class Optimizer:\n algo: str\n lr: float\n\n def __init__(self, algo: str, lr: float) -> None:\n self.algo = algo\n self.lr = lr\n\n def __repr__(self) -> str:\n return f"Optimizer(algo={self.algo},lr={self.lr})"\n\n\nclass Model:\n def __init__(self, optim_partial: Any, lr: float):\n super().__init__()\n self.optim = optim_partial(lr=lr)\n self.lr = lr\n\n def __repr__(self) -> str:\n return f"Model(Optimizer={self.optim},lr={self.lr})"\n')),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--5"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Config"',title:'"Config"'},"model:\n _target_: my_app.Model\n optim_partial:\n _partial_: true\n _target_: my_app.Optimizer\n algo: SGD\n lr: 0.01\n"))),(0,o.mdx)("div",{className:"col col--7"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Instantiation"',title:'"Instantiation"'},'model = instantiate(cfg.model)\nprint(model)\n# "Model(Optimizer=Optimizer(algo=SGD,lr=0.01),lr=0.01)\n')))),(0,o.mdx)("p",null,"If you are repeatedly instantiating the same config,\nusing ",(0,o.mdx)("inlineCode",{parentName:"p"},"_partial_=True")," may provide a significant speedup as compared with regular (non-partial) instantiation."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},"factory = instantiate(config, _partial_=True)\nobj = factory()\n")),(0,o.mdx)("p",null,"In the above example, repeatedly calling ",(0,o.mdx)("inlineCode",{parentName:"p"},"factory")," would be faster than repeatedly calling ",(0,o.mdx)("inlineCode",{parentName:"p"},"instantiate(config)"),".\nA caveat of this approach is that the same keyword arguments would be re-used in each call to ",(0,o.mdx)("inlineCode",{parentName:"p"},"factory"),"."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'class Foo:\n ...\n\nclass Bar:\n def __init__(self, foo):\n self.foo = foo\n\nbar_conf = {\n "_target_": "__main__.Bar",\n "foo": {"_target_": "__main__.Foo"},\n}\n\nbar_factory = instantiate(bar_conf, _partial_=True)\nbar1 = bar_factory()\nbar2 = bar_factory()\n\nassert bar1 is not bar2\nassert bar1.foo is bar2.foo # the `Foo` instance is re-used here\n')),(0,o.mdx)("p",null,"This does not apply if ",(0,o.mdx)("inlineCode",{parentName:"p"},"_partial_=False"),",\nin which case a new ",(0,o.mdx)("inlineCode",{parentName:"p"},"Foo")," instance would be created with each call to ",(0,o.mdx)("inlineCode",{parentName:"p"},"instantiate"),"."),(0,o.mdx)("h3",{id:"instantiation-of-builtins"},"Instantiation of builtins"),(0,o.mdx)("p",null,"The value of ",(0,o.mdx)("inlineCode",{parentName:"p"},"_target_")," passed to ",(0,o.mdx)("inlineCode",{parentName:"p"},"instantiate"),' should be a "dotpath" pointing\nto some callable that can be looked up via a combination of ',(0,o.mdx)("inlineCode",{parentName:"p"},"import")," and ",(0,o.mdx)("inlineCode",{parentName:"p"},"getattr"),".\nIf you want to target one of Python's ",(0,o.mdx)("a",{parentName:"p",href:"https://docs.python.org/3/library/functions.html"},"built-in functions")," (such as ",(0,o.mdx)("inlineCode",{parentName:"p"},"len")," or ",(0,o.mdx)("inlineCode",{parentName:"p"},"print")," or ",(0,o.mdx)("inlineCode",{parentName:"p"},"divmod"),"),\nyou will need to provide a dotpath looking up that function in Python's ",(0,o.mdx)("a",{parentName:"p",href:"https://docs.python.org/3/library/builtins.html"},(0,o.mdx)("inlineCode",{parentName:"a"},"builtins"))," module."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'from hydra.utils import instantiate\n# instantiate({"_target_": "len"}, [1,2,3]) # this gives an InstantiationException\ninstantiate({"_target_": "builtins.len"}, [1,2,3]) # this works, returns the number 3\n')),(0,o.mdx)("h3",{id:"dotpath-lookup-machinery"},"Dotpath lookup machinery"),(0,o.mdx)("p",null,"Hydra looks up a given ",(0,o.mdx)("inlineCode",{parentName:"p"},"_target_")," by attempting to find a module that\ncorresponds to a prefix of the given dotpath and then looking for an object in\nthat module corresponding to the dotpath's tail. For example, to look up a ",(0,o.mdx)("inlineCode",{parentName:"p"},"_target_"),"\ngiven by the dotpath ",(0,o.mdx)("inlineCode",{parentName:"p"},'"my_module.my_nested_module.my_object"'),", hydra first locates\nthe module ",(0,o.mdx)("inlineCode",{parentName:"p"},"my_module.my_nested_module"),", then find ",(0,o.mdx)("inlineCode",{parentName:"p"},"my_object")," inside that nested module."),(0,o.mdx)("p",null,"Hydra exposes an API allowing direct use of this dotpath lookup machinery.\nThe following two functions, which can be imported from the ",(0,o.mdx)(u,{to:"hydra/utils.py",mdxType:"GithubLink"},"hydra.utils")," module,\naccept a string-typed dotpath as an argument and return the located class/callable/object:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'def get_class(path: str) -> type:\n """\n Look up a class based on a dotpath.\n Fails if the path does not point to a class.\n\n >>> import my_module\n >>> from hydra.utils import get_class\n >>> assert get_class("my_module.MyClass") is my_module.MyClass\n """\n ...\n\ndef get_method(path: str) -> Callable[..., Any]:\n """\n Look up a callable based on a dotpath.\n Fails if the path does not point to a callable object.\n\n >>> import my_module\n >>> from hydra.utils import get_method\n >>> assert get_method("my_module.my_function") is my_module.my_function\n """\n ...\n\n# Alias for get_method\nget_static_method = get_method\n')))}f.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/02deea7a.8790c792.js b/assets/js/02deea7a.8790c792.js new file mode 100644 index 0000000000..747116b1f2 --- /dev/null +++ b/assets/js/02deea7a.8790c792.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[9634],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>d,MDXProvider:()=>c,mdx:()=>f,useMDXComponents:()=>p,withMDXComponents:()=>m});var a=n(96540);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function r(){return r=Object.assign||function(e){for(var t=1;t=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var d=a.createContext({}),m=function(e){return function(t){var n=p(t.components);return a.createElement(e,r({},t,{components:n}))}},p=function(e){var t=a.useContext(d),n=t;return e&&(n="function"==typeof e?e(t):s(s({},t),e)),n},c=function(e){var t=p(e.components);return a.createElement(d.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},g=a.forwardRef((function(e,t){var n=e.components,i=e.mdxType,r=e.originalType,o=e.parentName,d=l(e,["components","mdxType","originalType","parentName"]),m=p(n),c=i,g=m["".concat(o,".").concat(c)]||m[c]||u[c]||r;return n?a.createElement(g,s(s({ref:t},d),{},{components:n})):a.createElement(g,s({ref:t},d))}));function f(e,t){var n=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var r=n.length,o=new Array(r);o[0]=g;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s.mdxType="string"==typeof e?e:i,o[1]=s;for(var d=2;d{n.d(t,{A:()=>l,C:()=>d});var a=n(58168),i=n(96540),r=n(75489),o=n(44586),s=n(74098);function l(e){return i.createElement(r.default,(0,a.A)({},e,{to:(t=e.to,l=(0,s.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==l?void 0:l.name)?n:"current"]+t),target:"_blank"}));var t,n,l}function d(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return i.createElement(l,e,i.createElement("span",null,"\xa0"),i.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},63594:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>m,default:()=>f,frontMatter:()=>d,metadata:()=>p,toc:()=>c});var a,i=n(58168),r=n(98587),o=(n(96540),n(15680)),s=n(49595),l=["components"],d={id:"overview",title:"Instantiating objects with Hydra",sidebar_label:"Overview"},m=void 0,p={unversionedId:"advanced/instantiate_objects/overview",id:"version-1.3/advanced/instantiate_objects/overview",title:"Instantiating objects with Hydra",description:"One of the best ways to drive different behavior in an application is to instantiate different implementations of an interface.",source:"@site/versioned_docs/version-1.3/advanced/instantiate_objects/overview.md",sourceDirName:"advanced/instantiate_objects",slug:"/advanced/instantiate_objects/overview",permalink:"/docs/1.3/advanced/instantiate_objects/overview",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/advanced/instantiate_objects/overview.md",tags:[],version:"1.3",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"overview",title:"Instantiating objects with Hydra",sidebar_label:"Overview"},sidebar:"docs",previous:{title:"Packages",permalink:"/docs/1.3/advanced/overriding_packages"},next:{title:"Config files example",permalink:"/docs/1.3/advanced/instantiate_objects/config_files"}},c=[{value:"Simple usage",id:"simple-usage",children:[],level:3},{value:"Recursive instantiation",id:"recursive-instantiation",children:[],level:3},{value:"Disable recursive instantiation",id:"disable-recursive-instantiation",children:[],level:3},{value:"Parameter conversion strategies",id:"parameter-conversion-strategies",children:[],level:3},{value:"Partial Instantiation",id:"partial-instantiation",children:[],level:3},{value:"Instantiation of builtins",id:"instantiation-of-builtins",children:[],level:3},{value:"Dotpath lookup machinery",id:"dotpath-lookup-machinery",children:[],level:3}],u=(a="GithubLink",function(e){return console.warn("Component "+a+" was not imported, exported, or provided by MDXProvider as global scope"),(0,o.mdx)("div",e)}),g={toc:c};function f(e){var t=e.components,n=(0,r.A)(e,l);return(0,o.mdx)("wrapper",(0,i.A)({},g,n,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)(s.C,{text:"Example applications",to:"examples/instantiate",mdxType:"ExampleGithubLink"}),(0,o.mdx)("p",null,"One of the best ways to drive different behavior in an application is to instantiate different implementations of an interface.\nThe code using the instantiated object only knows the interface which remains constant, but the behavior\nis determined by the actual object instance."),(0,o.mdx)("p",null,"Hydra provides ",(0,o.mdx)("inlineCode",{parentName:"p"},"hydra.utils.instantiate()")," (and its alias ",(0,o.mdx)("inlineCode",{parentName:"p"},"hydra.utils.call()"),") for instantiating objects and calling functions. Prefer ",(0,o.mdx)("inlineCode",{parentName:"p"},"instantiate")," for creating objects and ",(0,o.mdx)("inlineCode",{parentName:"p"},"call")," for invoking functions."),(0,o.mdx)("p",null,"Call/instantiate supports:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"Constructing an object by calling the ",(0,o.mdx)("inlineCode",{parentName:"li"},"__init__")," method"),(0,o.mdx)("li",{parentName:"ul"},"Calling functions, static functions, class methods and other callable global objects")),(0,o.mdx)("details",null,(0,o.mdx)("summary",null,"Instantiate API (Expand for details)"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'def instantiate(config: Any, *args: Any, **kwargs: Any) -> Any:\n """\n :param config: An config object describing what to call and what params to use.\n In addition to the parameters, the config must contain:\n _target_ : target class or callable name (str)\n And may contain:\n _args_: List-like of positional arguments to pass to the target\n _recursive_: Construct nested objects as well (bool).\n True by default.\n may be overridden via a _recursive_ key in\n the kwargs\n _convert_: Conversion strategy\n none : Passed objects are DictConfig and ListConfig, default\n partial : Passed objects are converted to dict and list, with\n the exception of Structured Configs (and their fields).\n object : Passed objects are converted to dict and list.\n Structured Configs are converted to instances of the\n backing dataclass / attr class.\n all : Passed objects are dicts, lists and primitives without\n a trace of OmegaConf containers. Structured configs\n are converted to dicts / lists too.\n _partial_: If True, return functools.partial wrapped method or object\n False by default. Configure per target.\n :param args: Optional positional parameters pass-through\n :param kwargs: Optional named parameters to override\n parameters in the config object. Parameters not present\n in the config objects are being passed as is to the target.\n IMPORTANT: dataclasses instances in kwargs are interpreted as config\n and cannot be used as passthrough\n :return: if _target_ is a class name: the instantiated object\n if _target_ is a callable: the return value of the call\n """\n\n# Alias for instantiate\ncall = instantiate\n'))),(0,o.mdx)("br",null),(0,o.mdx)("p",null,"The config passed to these functions must have a key called ",(0,o.mdx)("inlineCode",{parentName:"p"},"_target_"),", with the value of a fully qualified class name, class method, static method or callable.\nFor convenience, ",(0,o.mdx)("inlineCode",{parentName:"p"},"None")," config results in a ",(0,o.mdx)("inlineCode",{parentName:"p"},"None")," object."),(0,o.mdx)("p",null,(0,o.mdx)("strong",{parentName:"p"},"Named arguments")," : Config fields (except reserved fields like ",(0,o.mdx)("inlineCode",{parentName:"p"},"_target_"),") are passed as named arguments to the target.\nNamed arguments in the config can be overridden by passing named argument with the same name in the ",(0,o.mdx)("inlineCode",{parentName:"p"},"instantiate()")," call-site."),(0,o.mdx)("p",null,(0,o.mdx)("strong",{parentName:"p"},"Positional arguments")," : The config may contain a ",(0,o.mdx)("inlineCode",{parentName:"p"},"_args_")," field representing positional arguments to pass to the target.\nThe positional arguments can be overridden together by passing positional arguments in the ",(0,o.mdx)("inlineCode",{parentName:"p"},"instantiate()")," call-site."),(0,o.mdx)("h3",{id:"simple-usage"},"Simple usage"),(0,o.mdx)("p",null,"Your application might have an Optimizer class:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Example class"',title:'"Example','class"':!0},"class Optimizer:\n algo: str\n lr: float\n\n def __init__(self, algo: str, lr: float) -> None:\n self.algo = algo\n self.lr = lr\n")),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Config"',title:'"Config"'},"optimizer:\n _target_: my_app.Optimizer\n algo: SGD\n lr: 0.01\n\n\n\n\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Instantiation"',title:'"Instantiation"'},"opt = instantiate(cfg.optimizer)\nprint(opt)\n# Optimizer(algo=SGD,lr=0.01)\n\n# override parameters on the call-site\nopt = instantiate(cfg.optimizer, lr=0.2)\nprint(opt)\n# Optimizer(algo=SGD,lr=0.2)\n")))),(0,o.mdx)("h3",{id:"recursive-instantiation"},"Recursive instantiation"),(0,o.mdx)("p",null,"Let's add a Dataset and a Trainer class. The trainer holds a Dataset and an Optimizer instances."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Additional classes"',title:'"Additional','classes"':!0},"class Dataset:\n name: str\n path: str\n\n def __init__(self, name: str, path: str) -> None:\n self.name = name\n self.path = path\n\n\nclass Trainer:\n def __init__(self, optimizer: Optimizer, dataset: Dataset) -> None:\n self.optimizer = optimizer\n self.dataset = dataset\n")),(0,o.mdx)("p",null,"With the following config, you can instantiate the whole thing with a single call:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Example config"',title:'"Example','config"':!0},"trainer:\n _target_: my_app.Trainer\n optimizer:\n _target_: my_app.Optimizer\n algo: SGD\n lr: 0.01\n dataset:\n _target_: my_app.Dataset\n name: Imagenet\n path: /datasets/imagenet\n")),(0,o.mdx)("p",null,"Hydra will instantiate nested objects recursively by default."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},"trainer = instantiate(cfg.trainer)\nprint(trainer)\n# Trainer(\n# optimizer=Optimizer(algo=SGD,lr=0.01),\n# dataset=Dataset(name=Imagenet, path=/datasets/imagenet)\n# )\n")),(0,o.mdx)("p",null,"You can override parameters for nested objects:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'trainer = instantiate(\n cfg.trainer,\n optimizer={"lr": 0.3},\n dataset={"name": "cifar10", "path": "/datasets/cifar10"},\n)\nprint(trainer)\n# Trainer(\n# optimizer=Optimizer(algo=SGD,lr=0.3),\n# dataset=Dataset(name=cifar10, path=/datasets/cifar10)\n# )\n')),(0,o.mdx)("p",null,"Similarly, positional arguments of nested objects can be overridden:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'obj = instantiate(\n cfg.object,\n # pass 1 and 2 as positional arguments to the target object\n 1, 2, \n # pass 3 and 4 as positional arguments to a nested child object\n child={"_args_": [3, 4]},\n)\n')),(0,o.mdx)("h3",{id:"disable-recursive-instantiation"},"Disable recursive instantiation"),(0,o.mdx)("p",null,"You can disable recursive instantiation by setting ",(0,o.mdx)("inlineCode",{parentName:"p"},"_recursive_")," to ",(0,o.mdx)("inlineCode",{parentName:"p"},"False")," in the config node or in the call-site\nIn that case the Trainer object will receive an OmegaConf DictConfig for nested dataset and optimizer instead of the instantiated objects."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},"optimizer = instantiate(cfg.trainer, _recursive_=False)\nprint(optimizer)\n")),(0,o.mdx)("p",null,"Output:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},"Trainer(\n optimizer={\n '_target_': 'my_app.Optimizer', 'algo': 'SGD', 'lr': 0.01\n },\n dataset={\n '_target_': 'my_app.Dataset', 'name': 'Imagenet', 'path': '/datasets/imagenet'\n }\n)\n")),(0,o.mdx)("h3",{id:"parameter-conversion-strategies"},"Parameter conversion strategies"),(0,o.mdx)("p",null,"By default, the parameters passed to the target are either primitives (int,\nfloat, bool etc) or OmegaConf containers (",(0,o.mdx)("inlineCode",{parentName:"p"},"DictConfig"),", ",(0,o.mdx)("inlineCode",{parentName:"p"},"ListConfig"),").\nOmegaConf containers have many advantages over primitive dicts and lists,\nincluding convenient attribute access for keys,\n",(0,o.mdx)("a",{parentName:"p",href:"https://omegaconf.readthedocs.io/en/latest/structured_config.html"},"duck-typing as instances of dataclasses or attrs classes"),", and\nsupport for ",(0,o.mdx)("a",{parentName:"p",href:"https://omegaconf.readthedocs.io/en/latest/usage.html#variable-interpolation"},"variable interpolation"),"\nand ",(0,o.mdx)("a",{parentName:"p",href:"https://omegaconf.readthedocs.io/en/latest/custom_resolvers.html"},"custom resolvers"),".\nIf the callable targeted by ",(0,o.mdx)("inlineCode",{parentName:"p"},"instantiate")," leverages OmegaConf's features, it\nwill make sense to pass ",(0,o.mdx)("inlineCode",{parentName:"p"},"DictConfig")," and ",(0,o.mdx)("inlineCode",{parentName:"p"},"ListConfig")," instances directly to\nthat callable."),(0,o.mdx)("p",null,"That being said, in many cases it's desired to pass normal Python dicts and\nlists, rather than ",(0,o.mdx)("inlineCode",{parentName:"p"},"DictConfig")," or ",(0,o.mdx)("inlineCode",{parentName:"p"},"ListConfig")," instances, as arguments to your\ncallable. You can change instantiate's argument conversion strategy using the\n",(0,o.mdx)("inlineCode",{parentName:"p"},"_convert_")," parameter. Supported values are:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},'"none"')," : Default behavior, Use OmegaConf containers"),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},'"partial"')," : Convert OmegaConf containers to dict and list, except\nStructured Configs, which remain as DictConfig instances."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},'"object"')," : Convert OmegaConf containers to dict and list, except Structured\nConfigs, which are converted to instances of the backing dataclass / attr\nclass using ",(0,o.mdx)("inlineCode",{parentName:"li"},"OmegaConf.to_object"),"."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},'"all"')," : Convert everything to primitive containers")),(0,o.mdx)("p",null,"The conversion strategy applies recursively to all subconfigs of the instantiation target.\nHere is an example demonstrating the various conversion strategies:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'from dataclasses import dataclass\nfrom omegaconf import DictConfig, OmegaConf\nfrom hydra.utils import instantiate\n\n@dataclass\nclass Foo:\n a: int = 123\n\nclass MyTarget:\n def __init__(self, foo, bar):\n self.foo = foo\n self.bar = bar\n\ncfg = OmegaConf.create(\n {\n "_target_": "__main__.MyTarget",\n "foo": Foo(),\n "bar": {"b": 456},\n }\n)\n\nobj_none = instantiate(cfg, _convert_="none")\nassert isinstance(obj_none, MyTarget)\nassert isinstance(obj_none.foo, DictConfig)\nassert isinstance(obj_none.bar, DictConfig)\n\nobj_partial = instantiate(cfg, _convert_="partial")\nassert isinstance(obj_partial, MyTarget)\nassert isinstance(obj_partial.foo, DictConfig)\nassert isinstance(obj_partial.bar, dict)\n\nobj_object = instantiate(cfg, _convert_="object")\nassert isinstance(obj_object, MyTarget)\nassert isinstance(obj_object.foo, Foo)\nassert isinstance(obj_object.bar, dict)\n\nobj_all = instantiate(cfg, _convert_="all")\nassert isinstance(obj_none, MyTarget)\nassert isinstance(obj_all.foo, dict)\nassert isinstance(obj_all.bar, dict)\n')),(0,o.mdx)("p",null,"Passing the ",(0,o.mdx)("inlineCode",{parentName:"p"},"_convert_")," keyword argument to ",(0,o.mdx)("inlineCode",{parentName:"p"},"instantiate")," has the same effect as defining\na ",(0,o.mdx)("inlineCode",{parentName:"p"},"_convert_")," attribute on your config object. Here is an example creating\ninstances of ",(0,o.mdx)("inlineCode",{parentName:"p"},"MyTarget")," that are equivalent to the above:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'cfg_none = OmegaConf.create({..., "_convert_": "none"})\nobj_none = instantiate(cfg_none)\n\ncfg_partial = OmegaConf.create({..., "_convert_": "partial"})\nobj_partial = instantiate(cfg_partial)\n\ncfg_object = OmegaConf.create({..., "_convert_": "object"})\nobj_object = instantiate(cfg_object)\n\ncfg_all = OmegaConf.create({..., "_convert_": "all"})\nobj_all = instantiate(cfg_all)\n')),(0,o.mdx)("h3",{id:"partial-instantiation"},"Partial Instantiation"),(0,o.mdx)("p",null,"Sometimes you may not set all parameters needed to instantiate an object from the configuration, in this case you can set\n",(0,o.mdx)("inlineCode",{parentName:"p"},"_partial_")," to be ",(0,o.mdx)("inlineCode",{parentName:"p"},"True")," to get a ",(0,o.mdx)("inlineCode",{parentName:"p"},"functools.partial")," wrapped object or method, then complete initializing the object in\nthe application code. Here is an example:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Example classes"',title:'"Example','classes"':!0},'class Optimizer:\n algo: str\n lr: float\n\n def __init__(self, algo: str, lr: float) -> None:\n self.algo = algo\n self.lr = lr\n\n def __repr__(self) -> str:\n return f"Optimizer(algo={self.algo},lr={self.lr})"\n\n\nclass Model:\n def __init__(self, optim_partial: Any, lr: float):\n super().__init__()\n self.optim = optim_partial(lr=lr)\n self.lr = lr\n\n def __repr__(self) -> str:\n return f"Model(Optimizer={self.optim},lr={self.lr})"\n')),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--5"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Config"',title:'"Config"'},"model:\n _target_: my_app.Model\n optim_partial:\n _partial_: true\n _target_: my_app.Optimizer\n algo: SGD\n lr: 0.01\n"))),(0,o.mdx)("div",{className:"col col--7"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Instantiation"',title:'"Instantiation"'},'model = instantiate(cfg.model)\nprint(model)\n# "Model(Optimizer=Optimizer(algo=SGD,lr=0.01),lr=0.01)\n')))),(0,o.mdx)("p",null,"If you are repeatedly instantiating the same config,\nusing ",(0,o.mdx)("inlineCode",{parentName:"p"},"_partial_=True")," may provide a significant speedup as compared with regular (non-partial) instantiation."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},"factory = instantiate(config, _partial_=True)\nobj = factory()\n")),(0,o.mdx)("p",null,"In the above example, repeatedly calling ",(0,o.mdx)("inlineCode",{parentName:"p"},"factory")," would be faster than repeatedly calling ",(0,o.mdx)("inlineCode",{parentName:"p"},"instantiate(config)"),".\nA caveat of this approach is that the same keyword arguments would be re-used in each call to ",(0,o.mdx)("inlineCode",{parentName:"p"},"factory"),"."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'class Foo:\n ...\n\nclass Bar:\n def __init__(self, foo):\n self.foo = foo\n\nbar_conf = {\n "_target_": "__main__.Bar",\n "foo": {"_target_": "__main__.Foo"},\n}\n\nbar_factory = instantiate(bar_conf, _partial_=True)\nbar1 = bar_factory()\nbar2 = bar_factory()\n\nassert bar1 is not bar2\nassert bar1.foo is bar2.foo # the `Foo` instance is re-used here\n')),(0,o.mdx)("p",null,"This does not apply if ",(0,o.mdx)("inlineCode",{parentName:"p"},"_partial_=False"),",\nin which case a new ",(0,o.mdx)("inlineCode",{parentName:"p"},"Foo")," instance would be created with each call to ",(0,o.mdx)("inlineCode",{parentName:"p"},"instantiate"),"."),(0,o.mdx)("h3",{id:"instantiation-of-builtins"},"Instantiation of builtins"),(0,o.mdx)("p",null,"The value of ",(0,o.mdx)("inlineCode",{parentName:"p"},"_target_")," passed to ",(0,o.mdx)("inlineCode",{parentName:"p"},"instantiate"),' should be a "dotpath" pointing\nto some callable that can be looked up via a combination of ',(0,o.mdx)("inlineCode",{parentName:"p"},"import")," and ",(0,o.mdx)("inlineCode",{parentName:"p"},"getattr"),".\nIf you want to target one of Python's ",(0,o.mdx)("a",{parentName:"p",href:"https://docs.python.org/3/library/functions.html"},"built-in functions")," (such as ",(0,o.mdx)("inlineCode",{parentName:"p"},"len")," or ",(0,o.mdx)("inlineCode",{parentName:"p"},"print")," or ",(0,o.mdx)("inlineCode",{parentName:"p"},"divmod"),"),\nyou will need to provide a dotpath looking up that function in Python's ",(0,o.mdx)("a",{parentName:"p",href:"https://docs.python.org/3/library/builtins.html"},(0,o.mdx)("inlineCode",{parentName:"a"},"builtins"))," module."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'from hydra.utils import instantiate\n# instantiate({"_target_": "len"}, [1,2,3]) # this gives an InstantiationException\ninstantiate({"_target_": "builtins.len"}, [1,2,3]) # this works, returns the number 3\n')),(0,o.mdx)("h3",{id:"dotpath-lookup-machinery"},"Dotpath lookup machinery"),(0,o.mdx)("p",null,"Hydra looks up a given ",(0,o.mdx)("inlineCode",{parentName:"p"},"_target_")," by attempting to find a module that\ncorresponds to a prefix of the given dotpath and then looking for an object in\nthat module corresponding to the dotpath's tail. For example, to look up a ",(0,o.mdx)("inlineCode",{parentName:"p"},"_target_"),"\ngiven by the dotpath ",(0,o.mdx)("inlineCode",{parentName:"p"},'"my_module.my_nested_module.my_object"'),", hydra first locates\nthe module ",(0,o.mdx)("inlineCode",{parentName:"p"},"my_module.my_nested_module"),", then find ",(0,o.mdx)("inlineCode",{parentName:"p"},"my_object")," inside that nested module."),(0,o.mdx)("p",null,"Hydra exposes an API allowing direct use of this dotpath lookup machinery.\nThe following two functions, which can be imported from the ",(0,o.mdx)(u,{to:"hydra/utils.py",mdxType:"GithubLink"},"hydra.utils")," module,\naccept a string-typed dotpath as an argument and return the located class/callable/object:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'def get_class(path: str) -> type:\n """\n Look up a class based on a dotpath.\n Fails if the path does not point to a class.\n\n >>> import my_module\n >>> from hydra.utils import get_class\n >>> assert get_class("my_module.MyClass") is my_module.MyClass\n """\n ...\n\ndef get_method(path: str) -> Callable[..., Any]:\n """\n Look up a callable based on a dotpath.\n Fails if the path does not point to a callable object.\n\n >>> import my_module\n >>> from hydra.utils import get_method\n >>> assert get_method("my_module.my_function") is my_module.my_function\n """\n ...\n\n# Alias for get_method\nget_static_method = get_method\n')))}f.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/03322abc.001c2d03.js b/assets/js/03322abc.001c2d03.js deleted file mode 100644 index b3597824cb..0000000000 --- a/assets/js/03322abc.001c2d03.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[5761],{15680:(e,t,a)=>{a.r(t),a.d(t,{MDXContext:()=>d,MDXProvider:()=>p,mdx:()=>g,useMDXComponents:()=>c,withMDXComponents:()=>m});var n=a(96540);function i(e,t,a){return t in e?Object.defineProperty(e,t,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[t]=a,e}function r(){return r=Object.assign||function(e){for(var t=1;t=0||(i[a]=e[a]);return i}(e,t);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(i[a]=e[a])}return i}var d=n.createContext({}),m=function(e){return function(t){var a=c(t.components);return n.createElement(e,r({},t,{components:a}))}},c=function(e){var t=n.useContext(d),a=t;return e&&(a="function"==typeof e?e(t):l(l({},t),e)),a},p=function(e){var t=c(e.components);return n.createElement(d.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},f=n.forwardRef((function(e,t){var a=e.components,i=e.mdxType,r=e.originalType,o=e.parentName,d=s(e,["components","mdxType","originalType","parentName"]),m=c(a),p=i,f=m["".concat(o,".").concat(p)]||m[p]||u[p]||r;return a?n.createElement(f,l(l({ref:t},d),{},{components:a})):n.createElement(f,l({ref:t},d))}));function g(e,t){var a=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var r=a.length,o=new Array(r);o[0]=f;var l={};for(var s in t)hasOwnProperty.call(t,s)&&(l[s]=t[s]);l.originalType=e,l.mdxType="string"==typeof e?e:i,o[1]=l;for(var d=2;d{a.r(t),a.d(t,{contentTitle:()=>s,default:()=>p,frontMatter:()=>l,metadata:()=>d,toc:()=>m});var n=a(58168),i=a(98587),r=(a(96540),a(15680)),o=["components"],l={id:"default_composition_order",title:"Changes to default composition order"},s=void 0,d={unversionedId:"upgrades/1.0_to_1.1/default_composition_order",id:"upgrades/1.0_to_1.1/default_composition_order",title:"Changes to default composition order",description:"Default composition order is changing in Hydra 1.1.",source:"@site/docs/upgrades/1.0_to_1.1/changes_to_default_composition_order.md",sourceDirName:"upgrades/1.0_to_1.1",slug:"/upgrades/1.0_to_1.1/default_composition_order",permalink:"/docs/upgrades/1.0_to_1.1/default_composition_order",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/upgrades/1.0_to_1.1/changes_to_default_composition_order.md",tags:[],version:"current",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"default_composition_order",title:"Changes to default composition order"},sidebar:"docs",previous:{title:"Changes to @hydra.main() and hydra.initialize()",permalink:"/docs/upgrades/1.0_to_1.1/changes_to_hydra_main_config_path"},next:{title:"Defaults List Overrides",permalink:"/docs/upgrades/1.0_to_1.1/defaults_list_override"}},m=[{value:"Migration",id:"migration",children:[{value:"Primary config is a YAML file",id:"primary-config-is-a-yaml-file",children:[],level:3},{value:"Primary config is a Structured Config",id:"primary-config-is-a-structured-config",children:[],level:3},{value:"Primary config is a config file with a Structured Config schema",id:"primary-config-is-a-config-file-with-a-structured-config-schema",children:[],level:3},{value:"Compatibility with both Hydra 1.0 and 1.1",id:"compatibility-with-both-hydra-10-and-11",children:[],level:3}],level:2}],c={toc:m};function p(e){var t=e.components,a=(0,i.A)(e,o);return(0,r.mdx)("wrapper",(0,n.A)({},c,a,{components:t,mdxType:"MDXLayout"}),(0,r.mdx)("p",null,"Default composition order is changing in Hydra 1.1."),(0,r.mdx)("p",null,"For this example, let's assume the following two configs:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - foo: bar\n\nfoo:\n x: 10\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="foo/bar.yaml"',title:'"foo/bar.yaml"'},"# @package _group_\nx: 20\n\n\n\n")))),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col"},(0,r.mdx)("p",null,"In ",(0,r.mdx)("strong",{parentName:"p"},"Hydra 1.0"),", configs from the Defaults List are overriding ",(0,r.mdx)("em",{parentName:"p"},"config.yaml"),", resulting in the following output:")),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{2}","{2}":!0},"foo:\n x: 20\n")))),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col"},(0,r.mdx)("p",null,"As of ",(0,r.mdx)("strong",{parentName:"p"},"Hydra 1.1"),", ",(0,r.mdx)("em",{parentName:"p"},"config.yaml")," is overriding configs from the Defaults List, resulting in the following output:")),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{2}","{2}":!0},"foo:\n x: 10\n")))),(0,r.mdx)("h2",{id:"migration"},"Migration"),(0,r.mdx)("p",null,"If your application uses ",(0,r.mdx)("inlineCode",{parentName:"p"},"hydra.main"),", the best way to verify that updating Hydra versions does not change your job configurations is to compare the output of ",(0,r.mdx)("inlineCode",{parentName:"p"},"python my_app.py --cfg job")," on both the new and old Hydra versions. If your application uses the Compose API, please make sure you have comprehensive unit tests on the composed configuration."),(0,r.mdx)("h3",{id:"primary-config-is-a-yaml-file"},"Primary config is a YAML file"),(0,r.mdx)("p",null,"To ensure this change is not missed by people migrating from Hydra 1.0, Hydra 1.1 issues a warning if the Defaults List in the primary config is missing ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_"),", and there are config values in addition to the Defaults List.",(0,r.mdx)("br",{parentName:"p"}),"\n","To address the warning, add ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," to the Defaults List of the primary config."),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"If the new behavior works for your application, append ",(0,r.mdx)("inlineCode",{parentName:"li"},"_self_")," to the end of the Defaults List."),(0,r.mdx)("li",{parentName:"ul"},"If your application requires the previous behavior, insert ",(0,r.mdx)("inlineCode",{parentName:"li"},"_self_")," as the first item in your Defaults List.")),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {2}',title:'"config.yaml"',"{2}":!0},"defaults:\n - _self_\n - foo: bar\n\nfoo:\n x: 10\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Output config"',title:'"Output','config"':!0},"foo:\n x: 20\n\n\n\n\n")))),(0,r.mdx)("p",null,"The Defaults List is described ",(0,r.mdx)("a",{parentName:"p",href:"/docs/advanced/defaults_list"},"here"),"."),(0,r.mdx)("h3",{id:"primary-config-is-a-structured-config"},"Primary config is a Structured Config"),(0,r.mdx)("p",null,"Structured Configs used as primary config may see changes as well.\nYou should add ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," to the defaults list to indicate the composition order. In such cases you will typically want ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," to be the first item in the defaults list. "),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python",metastring:"{3,14}","{3,14}":!0},'defaults = [\n "_self_",\n {"db": "mysql"}\n]\n\n@dataclass\nclass Config:\n # this is unfortunately verbose due to @dataclass limitations\n defaults: List[Any] = field(default_factory=lambda: defaults)\n\n # Hydra will populate this field based on the defaults list\n db: Any = MISSING\n')),(0,r.mdx)("h3",{id:"primary-config-is-a-config-file-with-a-structured-config-schema"},"Primary config is a config file with a Structured Config schema"),(0,r.mdx)("p",null,"If you use Structured Config as a schema for your primary config, be sure to add ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," after the schema in the Defaults List, otherwise the schema will override the config instead of the other way around."),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app.py"',title:'"my_app.py"'},'@dataclass\nclass Config:\n host: str = "localhost"\n port: int = 8080\n\ncs.store(name="base_config", \n node=Config)\n'))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'{3,5} title="config.yaml"',"{3,5}":!0,title:'"config.yaml"'},"defaults:\n - base_config # schema\n - _self_ # after schema\n\nport: 3306\n\n\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'{2} title="Output config"',"{2}":!0,title:'"Output','config"':!0},"host: localhost # schema\nport: 3306 # config.yaml\n\n\n\n\n\n")))),(0,r.mdx)("h3",{id:"compatibility-with-both-hydra-10-and-11"},"Compatibility with both Hydra 1.0 and 1.1"),(0,r.mdx)("p",null,"If your config must be compatible with both Hydra 1.0 and 1.1, Insert ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," as the first item in the Defaults List.\nHydra 1.0.7 (or newer releases in Hydra 1.0) ignores ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," in the Defaults List and Hydra 1.1 will compose the same config as Hydra 1.0 if ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," is the first item."))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/03322abc.a11bbc3f.js b/assets/js/03322abc.a11bbc3f.js new file mode 100644 index 0000000000..88b058d095 --- /dev/null +++ b/assets/js/03322abc.a11bbc3f.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[5761],{15680:(e,t,a)=>{a.r(t),a.d(t,{MDXContext:()=>d,MDXProvider:()=>p,mdx:()=>g,useMDXComponents:()=>c,withMDXComponents:()=>m});var n=a(96540);function i(e,t,a){return t in e?Object.defineProperty(e,t,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[t]=a,e}function r(){return r=Object.assign||function(e){for(var t=1;t=0||(i[a]=e[a]);return i}(e,t);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(i[a]=e[a])}return i}var d=n.createContext({}),m=function(e){return function(t){var a=c(t.components);return n.createElement(e,r({},t,{components:a}))}},c=function(e){var t=n.useContext(d),a=t;return e&&(a="function"==typeof e?e(t):l(l({},t),e)),a},p=function(e){var t=c(e.components);return n.createElement(d.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},f=n.forwardRef((function(e,t){var a=e.components,i=e.mdxType,r=e.originalType,o=e.parentName,d=s(e,["components","mdxType","originalType","parentName"]),m=c(a),p=i,f=m["".concat(o,".").concat(p)]||m[p]||u[p]||r;return a?n.createElement(f,l(l({ref:t},d),{},{components:a})):n.createElement(f,l({ref:t},d))}));function g(e,t){var a=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var r=a.length,o=new Array(r);o[0]=f;var l={};for(var s in t)hasOwnProperty.call(t,s)&&(l[s]=t[s]);l.originalType=e,l.mdxType="string"==typeof e?e:i,o[1]=l;for(var d=2;d{a.r(t),a.d(t,{contentTitle:()=>s,default:()=>p,frontMatter:()=>l,metadata:()=>d,toc:()=>m});var n=a(58168),i=a(98587),r=(a(96540),a(15680)),o=["components"],l={id:"default_composition_order",title:"Changes to default composition order"},s=void 0,d={unversionedId:"upgrades/1.0_to_1.1/default_composition_order",id:"upgrades/1.0_to_1.1/default_composition_order",title:"Changes to default composition order",description:"Default composition order is changing in Hydra 1.1.",source:"@site/docs/upgrades/1.0_to_1.1/changes_to_default_composition_order.md",sourceDirName:"upgrades/1.0_to_1.1",slug:"/upgrades/1.0_to_1.1/default_composition_order",permalink:"/docs/upgrades/1.0_to_1.1/default_composition_order",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/upgrades/1.0_to_1.1/changes_to_default_composition_order.md",tags:[],version:"current",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"default_composition_order",title:"Changes to default composition order"},sidebar:"docs",previous:{title:"Changes to @hydra.main() and hydra.initialize()",permalink:"/docs/upgrades/1.0_to_1.1/changes_to_hydra_main_config_path"},next:{title:"Defaults List Overrides",permalink:"/docs/upgrades/1.0_to_1.1/defaults_list_override"}},m=[{value:"Migration",id:"migration",children:[{value:"Primary config is a YAML file",id:"primary-config-is-a-yaml-file",children:[],level:3},{value:"Primary config is a Structured Config",id:"primary-config-is-a-structured-config",children:[],level:3},{value:"Primary config is a config file with a Structured Config schema",id:"primary-config-is-a-config-file-with-a-structured-config-schema",children:[],level:3},{value:"Compatibility with both Hydra 1.0 and 1.1",id:"compatibility-with-both-hydra-10-and-11",children:[],level:3}],level:2}],c={toc:m};function p(e){var t=e.components,a=(0,i.A)(e,o);return(0,r.mdx)("wrapper",(0,n.A)({},c,a,{components:t,mdxType:"MDXLayout"}),(0,r.mdx)("p",null,"Default composition order is changing in Hydra 1.1."),(0,r.mdx)("p",null,"For this example, let's assume the following two configs:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - foo: bar\n\nfoo:\n x: 10\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="foo/bar.yaml"',title:'"foo/bar.yaml"'},"# @package _group_\nx: 20\n\n\n\n")))),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col"},(0,r.mdx)("p",null,"In ",(0,r.mdx)("strong",{parentName:"p"},"Hydra 1.0"),", configs from the Defaults List are overriding ",(0,r.mdx)("em",{parentName:"p"},"config.yaml"),", resulting in the following output:")),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{2}","{2}":!0},"foo:\n x: 20\n")))),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col"},(0,r.mdx)("p",null,"As of ",(0,r.mdx)("strong",{parentName:"p"},"Hydra 1.1"),", ",(0,r.mdx)("em",{parentName:"p"},"config.yaml")," is overriding configs from the Defaults List, resulting in the following output:")),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{2}","{2}":!0},"foo:\n x: 10\n")))),(0,r.mdx)("h2",{id:"migration"},"Migration"),(0,r.mdx)("p",null,"If your application uses ",(0,r.mdx)("inlineCode",{parentName:"p"},"hydra.main"),", the best way to verify that updating Hydra versions does not change your job configurations is to compare the output of ",(0,r.mdx)("inlineCode",{parentName:"p"},"python my_app.py --cfg job")," on both the new and old Hydra versions. If your application uses the Compose API, please make sure you have comprehensive unit tests on the composed configuration."),(0,r.mdx)("h3",{id:"primary-config-is-a-yaml-file"},"Primary config is a YAML file"),(0,r.mdx)("p",null,"To ensure this change is not missed by people migrating from Hydra 1.0, Hydra 1.1 issues a warning if the Defaults List in the primary config is missing ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_"),", and there are config values in addition to the Defaults List.",(0,r.mdx)("br",{parentName:"p"}),"\n","To address the warning, add ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," to the Defaults List of the primary config."),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"If the new behavior works for your application, append ",(0,r.mdx)("inlineCode",{parentName:"li"},"_self_")," to the end of the Defaults List."),(0,r.mdx)("li",{parentName:"ul"},"If your application requires the previous behavior, insert ",(0,r.mdx)("inlineCode",{parentName:"li"},"_self_")," as the first item in your Defaults List.")),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {2}',title:'"config.yaml"',"{2}":!0},"defaults:\n - _self_\n - foo: bar\n\nfoo:\n x: 10\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Output config"',title:'"Output','config"':!0},"foo:\n x: 20\n\n\n\n\n")))),(0,r.mdx)("p",null,"The Defaults List is described ",(0,r.mdx)("a",{parentName:"p",href:"/docs/advanced/defaults_list"},"here"),"."),(0,r.mdx)("h3",{id:"primary-config-is-a-structured-config"},"Primary config is a Structured Config"),(0,r.mdx)("p",null,"Structured Configs used as primary config may see changes as well.\nYou should add ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," to the defaults list to indicate the composition order. In such cases you will typically want ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," to be the first item in the defaults list. "),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python",metastring:"{3,14}","{3,14}":!0},'defaults = [\n "_self_",\n {"db": "mysql"}\n]\n\n@dataclass\nclass Config:\n # this is unfortunately verbose due to @dataclass limitations\n defaults: List[Any] = field(default_factory=lambda: defaults)\n\n # Hydra will populate this field based on the defaults list\n db: Any = MISSING\n')),(0,r.mdx)("h3",{id:"primary-config-is-a-config-file-with-a-structured-config-schema"},"Primary config is a config file with a Structured Config schema"),(0,r.mdx)("p",null,"If you use Structured Config as a schema for your primary config, be sure to add ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," after the schema in the Defaults List, otherwise the schema will override the config instead of the other way around."),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app.py"',title:'"my_app.py"'},'@dataclass\nclass Config:\n host: str = "localhost"\n port: int = 8080\n\ncs.store(name="base_config", \n node=Config)\n'))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'{3,5} title="config.yaml"',"{3,5}":!0,title:'"config.yaml"'},"defaults:\n - base_config # schema\n - _self_ # after schema\n\nport: 3306\n\n\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'{2} title="Output config"',"{2}":!0,title:'"Output','config"':!0},"host: localhost # schema\nport: 3306 # config.yaml\n\n\n\n\n\n")))),(0,r.mdx)("h3",{id:"compatibility-with-both-hydra-10-and-11"},"Compatibility with both Hydra 1.0 and 1.1"),(0,r.mdx)("p",null,"If your config must be compatible with both Hydra 1.0 and 1.1, Insert ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," as the first item in the Defaults List.\nHydra 1.0.7 (or newer releases in Hydra 1.0) ignores ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," in the Defaults List and Hydra 1.1 will compose the same config as Hydra 1.0 if ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," is the first item."))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/0413c37e.7d97f50c.js b/assets/js/0413c37e.7d97f50c.js new file mode 100644 index 0000000000..b818481a02 --- /dev/null +++ b/assets/js/0413c37e.7d97f50c.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[9101],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>u,MDXProvider:()=>s,mdx:()=>f,useMDXComponents:()=>c,withMDXComponents:()=>d});var r=t(96540);function i(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function o(){return o=Object.assign||function(e){for(var n=1;n=0||(i[t]=e[t]);return i}(e,n);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(i[t]=e[t])}return i}var u=r.createContext({}),d=function(e){return function(n){var t=c(n.components);return r.createElement(e,o({},n,{components:t}))}},c=function(e){var n=r.useContext(u),t=n;return e&&(t="function"==typeof e?e(n):l(l({},n),e)),t},s=function(e){var n=c(e.components);return r.createElement(u.Provider,{value:n},e.children)},m={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},g=r.forwardRef((function(e,n){var t=e.components,i=e.mdxType,o=e.originalType,a=e.parentName,u=p(e,["components","mdxType","originalType","parentName"]),d=c(t),s=i,g=d["".concat(a,".").concat(s)]||d[s]||m[s]||o;return t?r.createElement(g,l(l({ref:n},u),{},{components:t})):r.createElement(g,l({ref:n},u))}));function f(e,n){var t=arguments,i=n&&n.mdxType;if("string"==typeof e||i){var o=t.length,a=new Array(o);a[0]=g;var l={};for(var p in n)hasOwnProperty.call(n,p)&&(l[p]=n[p]);l.originalType=e,l.mdxType="string"==typeof e?e:i,a[1]=l;for(var u=2;u{t.r(n),t.d(n,{contentTitle:()=>p,default:()=>s,frontMatter:()=>l,metadata:()=>u,toc:()=>d});var r=t(58168),i=t(98587),o=(t(96540),t(15680)),a=["components"],l={id:"debugging",title:"Debugging",sidebar_label:"Debugging"},p=void 0,u={unversionedId:"tutorials/basic/running_your_app/debugging",id:"version-1.2/tutorials/basic/running_your_app/debugging",title:"Debugging",description:"Hydra provides a few options to improve debuggability.",source:"@site/versioned_docs/version-1.2/tutorials/basic/running_your_app/5_debugging.md",sourceDirName:"tutorials/basic/running_your_app",slug:"/tutorials/basic/running_your_app/debugging",permalink:"/docs/1.2/tutorials/basic/running_your_app/debugging",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/tutorials/basic/running_your_app/5_debugging.md",tags:[],version:"1.2",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:5,frontMatter:{id:"debugging",title:"Debugging",sidebar_label:"Debugging"},sidebar:"docs",previous:{title:"Logging",permalink:"/docs/1.2/tutorials/basic/running_your_app/logging"},next:{title:"Tab completion",permalink:"/docs/1.2/tutorials/basic/running_your_app/tab_completion"}},d=[{value:"Printing the configuration",id:"printing-the-configuration",children:[],level:3},{value:"Info",id:"info",children:[],level:3}],c={toc:d};function s(e){var n=e.components,t=(0,i.A)(e,a);return(0,o.mdx)("wrapper",(0,r.A)({},c,t,{components:n,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"Hydra provides a few options to improve debuggability."),(0,o.mdx)("h3",{id:"printing-the-configuration"},"Printing the configuration"),(0,o.mdx)("p",null,"Print the config for your app without running your function by adding ",(0,o.mdx)("inlineCode",{parentName:"p"},"--cfg")," or ",(0,o.mdx)("inlineCode",{parentName:"p"},"-c")," to the command line."),(0,o.mdx)("p",null,"The ",(0,o.mdx)("inlineCode",{parentName:"p"},"--cfg")," option takes one argument indicating which part of the config to print:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"job"),": Your config"),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"hydra"),": Hydra's config"),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"all"),": The full config, which is a union of ",(0,o.mdx)("inlineCode",{parentName:"li"},"job")," and ",(0,o.mdx)("inlineCode",{parentName:"li"},"hydra"),".")),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"# A normal run:\n$ python my_app.py\nMySQL connecting to localhost with user=root and password=1234\n\n# just show the config without running your function:\n$ python my_app.py --cfg job\ndb:\n host: localhost\n user: root\n password: 1234\n")),(0,o.mdx)("p",null,"The printed config includes any modifications done via the command line:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{3}","{3}":!0},"$ python my_app.py db.host=10.0.0.1 --cfg job\ndb:\n host: 10.0.0.1\n user: root\n password: 1234\n")),(0,o.mdx)("p",null,"You can use --package or -p to display a subset of the configuration:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"python my_app.py --cfg hydra --package hydra.job\n# @package hydra.job\nname: my_app\nconfig_name: config\n...\n")),(0,o.mdx)("p",null,"By default, config interpolations are not resolved. To print resolved config use the ",(0,o.mdx)("inlineCode",{parentName:"p"},"--resolve")," flag in addition to the ",(0,o.mdx)("inlineCode",{parentName:"p"},"--cfg")," flag"),(0,o.mdx)("h3",{id:"info"},"Info"),(0,o.mdx)("p",null,"The ",(0,o.mdx)("inlineCode",{parentName:"p"},"--info")," flag can provide information about various aspects of Hydra and your application:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"--info all"),": Default behavior, prints everything"),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"--info config"),": Prints information useful to understanding the config composition:",(0,o.mdx)("br",{parentName:"li"}),"Config Search Path, Defaults Tree, Defaults List and the final config."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"--info defaults"),": Prints the Final Defaults List"),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"--info defaults-tree"),": Prints the Defaults Tree"),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"--info plugins"),": Prints information about installed plugins")))}s.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/0413c37e.a05f483e.js b/assets/js/0413c37e.a05f483e.js deleted file mode 100644 index 2eae53a8ca..0000000000 --- a/assets/js/0413c37e.a05f483e.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[9101],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>u,MDXProvider:()=>s,mdx:()=>f,useMDXComponents:()=>c,withMDXComponents:()=>d});var r=t(96540);function i(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function o(){return o=Object.assign||function(e){for(var n=1;n=0||(i[t]=e[t]);return i}(e,n);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(i[t]=e[t])}return i}var u=r.createContext({}),d=function(e){return function(n){var t=c(n.components);return r.createElement(e,o({},n,{components:t}))}},c=function(e){var n=r.useContext(u),t=n;return e&&(t="function"==typeof e?e(n):l(l({},n),e)),t},s=function(e){var n=c(e.components);return r.createElement(u.Provider,{value:n},e.children)},m={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},g=r.forwardRef((function(e,n){var t=e.components,i=e.mdxType,o=e.originalType,a=e.parentName,u=p(e,["components","mdxType","originalType","parentName"]),d=c(t),s=i,g=d["".concat(a,".").concat(s)]||d[s]||m[s]||o;return t?r.createElement(g,l(l({ref:n},u),{},{components:t})):r.createElement(g,l({ref:n},u))}));function f(e,n){var t=arguments,i=n&&n.mdxType;if("string"==typeof e||i){var o=t.length,a=new Array(o);a[0]=g;var l={};for(var p in n)hasOwnProperty.call(n,p)&&(l[p]=n[p]);l.originalType=e,l.mdxType="string"==typeof e?e:i,a[1]=l;for(var u=2;u{t.r(n),t.d(n,{contentTitle:()=>p,default:()=>s,frontMatter:()=>l,metadata:()=>u,toc:()=>d});var r=t(58168),i=t(98587),o=(t(96540),t(15680)),a=["components"],l={id:"debugging",title:"Debugging",sidebar_label:"Debugging"},p=void 0,u={unversionedId:"tutorials/basic/running_your_app/debugging",id:"version-1.2/tutorials/basic/running_your_app/debugging",title:"Debugging",description:"Hydra provides a few options to improve debuggability.",source:"@site/versioned_docs/version-1.2/tutorials/basic/running_your_app/5_debugging.md",sourceDirName:"tutorials/basic/running_your_app",slug:"/tutorials/basic/running_your_app/debugging",permalink:"/docs/1.2/tutorials/basic/running_your_app/debugging",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/tutorials/basic/running_your_app/5_debugging.md",tags:[],version:"1.2",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:5,frontMatter:{id:"debugging",title:"Debugging",sidebar_label:"Debugging"},sidebar:"docs",previous:{title:"Logging",permalink:"/docs/1.2/tutorials/basic/running_your_app/logging"},next:{title:"Tab completion",permalink:"/docs/1.2/tutorials/basic/running_your_app/tab_completion"}},d=[{value:"Printing the configuration",id:"printing-the-configuration",children:[],level:3},{value:"Info",id:"info",children:[],level:3}],c={toc:d};function s(e){var n=e.components,t=(0,i.A)(e,a);return(0,o.mdx)("wrapper",(0,r.A)({},c,t,{components:n,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"Hydra provides a few options to improve debuggability."),(0,o.mdx)("h3",{id:"printing-the-configuration"},"Printing the configuration"),(0,o.mdx)("p",null,"Print the config for your app without running your function by adding ",(0,o.mdx)("inlineCode",{parentName:"p"},"--cfg")," or ",(0,o.mdx)("inlineCode",{parentName:"p"},"-c")," to the command line."),(0,o.mdx)("p",null,"The ",(0,o.mdx)("inlineCode",{parentName:"p"},"--cfg")," option takes one argument indicating which part of the config to print:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"job"),": Your config"),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"hydra"),": Hydra's config"),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"all"),": The full config, which is a union of ",(0,o.mdx)("inlineCode",{parentName:"li"},"job")," and ",(0,o.mdx)("inlineCode",{parentName:"li"},"hydra"),".")),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"# A normal run:\n$ python my_app.py\nMySQL connecting to localhost with user=root and password=1234\n\n# just show the config without running your function:\n$ python my_app.py --cfg job\ndb:\n host: localhost\n user: root\n password: 1234\n")),(0,o.mdx)("p",null,"The printed config includes any modifications done via the command line:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{3}","{3}":!0},"$ python my_app.py db.host=10.0.0.1 --cfg job\ndb:\n host: 10.0.0.1\n user: root\n password: 1234\n")),(0,o.mdx)("p",null,"You can use --package or -p to display a subset of the configuration:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"python my_app.py --cfg hydra --package hydra.job\n# @package hydra.job\nname: my_app\nconfig_name: config\n...\n")),(0,o.mdx)("p",null,"By default, config interpolations are not resolved. To print resolved config use the ",(0,o.mdx)("inlineCode",{parentName:"p"},"--resolve")," flag in addition to the ",(0,o.mdx)("inlineCode",{parentName:"p"},"--cfg")," flag"),(0,o.mdx)("h3",{id:"info"},"Info"),(0,o.mdx)("p",null,"The ",(0,o.mdx)("inlineCode",{parentName:"p"},"--info")," flag can provide information about various aspects of Hydra and your application:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"--info all"),": Default behavior, prints everything"),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"--info config"),": Prints information useful to understanding the config composition:",(0,o.mdx)("br",{parentName:"li"}),"Config Search Path, Defaults Tree, Defaults List and the final config."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"--info defaults"),": Prints the Final Defaults List"),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"--info defaults-tree"),": Prints the Defaults Tree"),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"--info plugins"),": Prints information about installed plugins")))}s.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/043fc566.90a6a7b8.js b/assets/js/043fc566.90a6a7b8.js deleted file mode 100644 index 49e291f515..0000000000 --- a/assets/js/043fc566.90a6a7b8.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[512],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>m,MDXProvider:()=>c,mdx:()=>h,useMDXComponents:()=>s,withMDXComponents:()=>d});var t=a(96540);function r(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(r[a]=e[a]);return r}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(r[a]=e[a])}return r}var m=t.createContext({}),d=function(e){return function(n){var a=s(n.components);return t.createElement(e,i({},n,{components:a}))}},s=function(e){var n=t.useContext(m),a=n;return e&&(a="function"==typeof e?e(n):p(p({},n),e)),a},c=function(e){var n=s(e.components);return t.createElement(m.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return t.createElement(t.Fragment,{},n)}},x=t.forwardRef((function(e,n){var a=e.components,r=e.mdxType,i=e.originalType,o=e.parentName,m=l(e,["components","mdxType","originalType","parentName"]),d=s(a),c=r,x=d["".concat(o,".").concat(c)]||d[c]||u[c]||i;return a?t.createElement(x,p(p({ref:n},m),{},{components:a})):t.createElement(x,p({ref:n},m))}));function h(e,n){var a=arguments,r=n&&n.mdxType;if("string"==typeof e||r){var i=a.length,o=new Array(i);o[0]=x;var p={};for(var l in n)hasOwnProperty.call(n,l)&&(p[l]=n[l]);p.originalType=e,p.mdxType="string"==typeof e?e:r,o[1]=p;for(var m=2;m{a.r(n),a.d(n,{contentTitle:()=>l,default:()=>c,frontMatter:()=>p,metadata:()=>m,toc:()=>d});var t=a(58168),r=a(98587),i=(a(96540),a(15680)),o=["components"],p={id:"ax_sweeper",title:"Ax Sweeper plugin",sidebar_label:"Ax Sweeper plugin"},l=void 0,m={unversionedId:"plugins/ax_sweeper",id:"version-1.0/plugins/ax_sweeper",title:"Ax Sweeper plugin",description:"PyPI",source:"@site/versioned_docs/version-1.0/plugins/ax_sweeper.md",sourceDirName:"plugins",slug:"/plugins/ax_sweeper",permalink:"/docs/1.0/plugins/ax_sweeper",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.0/plugins/ax_sweeper.md",tags:[],version:"1.0",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"ax_sweeper",title:"Ax Sweeper plugin",sidebar_label:"Ax Sweeper plugin"},sidebar:"version-1.0/docs",previous:{title:"Submitit Launcher plugin",permalink:"/docs/1.0/plugins/submitit_launcher"},next:{title:"Nevergrad Sweeper plugin",permalink:"/docs/1.0/plugins/nevergrad_sweeper"}},d=[{value:"Installation",id:"installation",children:[],level:3},{value:"Usage",id:"usage",children:[],level:3}],s={toc:d};function c(e){var n=e.components,a=(0,r.A)(e,o);return(0,i.mdx)("wrapper",(0,t.A)({},s,a,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,(0,i.mdx)("a",{parentName:"p",href:"https://img.shields.io/pypi/v/hydra-ax-sweeper"},(0,i.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/v/hydra-ax-sweeper",alt:"PyPI"})),"\n",(0,i.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/l/hydra-ax-sweeper",alt:"PyPI - License"}),"\n",(0,i.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/pyversions/hydra-ax-sweeper",alt:"PyPI - Python Version"}),"\n",(0,i.mdx)("a",{parentName:"p",href:"https://pypistats.org/packages/hydra-ax-sweeper"},(0,i.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/dm/hydra-ax-sweeper.svg",alt:"PyPI - Downloads"})),"\n",(0,i.mdx)("a",{parentName:"p",href:"https://github.com/facebookresearch/hydra/tree/1.0_branch/plugins/hydra_ax_sweeper/example"},(0,i.mdx)("img",{parentName:"a",src:"https://img.shields.io/badge/-Example%20application-informational",alt:"Example application"})),"\n",(0,i.mdx)("a",{parentName:"p",href:"https://github.com/facebookresearch/hydra/tree/1.0_branch/plugins/hydra_ax_sweeper"},(0,i.mdx)("img",{parentName:"a",src:"https://img.shields.io/badge/-Plugin%20source-informational",alt:"Plugin source"}))),(0,i.mdx)("p",null,"This plugin provides a mechanism for Hydra applications to use the ",(0,i.mdx)("a",{parentName:"p",href:"https://ax.dev/"},"Adaptive Experimentation Platform, aka Ax"),". Ax can optimize any experiment - machine learning experiments, A/B tests, and simulations. "),(0,i.mdx)("h3",{id:"installation"},"Installation"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"pip install hydra-ax-sweeper --upgrade\n")),(0,i.mdx)("h3",{id:"usage"},"Usage"),(0,i.mdx)("p",null,"Once installed, add ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra/sweeper=ax")," to your command line. Alternatively, override ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra/sweeper")," in your config:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - hydra/sweeper: ax\n")),(0,i.mdx)("p",null,"We include an example of how to use this plugin. The file ",(0,i.mdx)("a",{parentName:"p",href:"https://github.com/facebookresearch/hydra/blob/master/plugins/hydra_ax_sweeper/example/banana.py"},(0,i.mdx)("inlineCode",{parentName:"a"},"example/banana.py"))," implements the ",(0,i.mdx)("a",{parentName:"p",href:"https://en.wikipedia.org/wiki/Rosenbrock_function"},"Rosenbrock function (aka Banana function)"),". The return value of the function should be the value that we want to optimize."),(0,i.mdx)("p",null,"To compute the best parameters for the Banana function, clone the code and run the following command in the ",(0,i.mdx)("inlineCode",{parentName:"p"},"plugins/hydra_ax_sweeper")," directory:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre"},"python example/banana.py -m 'banana.x=int(interval(-5, 5))' 'banana.y=interval(-5, 10.1)'\n")),(0,i.mdx)("p",null,"The output of a run looks like:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre"},"[HYDRA] AxSweeper is optimizing the following parameters:\nbanana.x: range=[-5, 5], type = int\nbanana.y: range=[-5.0, 10.1], type = float\nax.modelbridge.dispatch_utils: Using Bayesian Optimization generation strategy: GenerationStrategy(name='Sobol+GPEI', steps=[Sobol for 5 arms, GPEI for subsequent arms], generated 0 arm(s) so far). Iterations after 5 will take longer to generate due to model-fitting.\nAxSweeper is launching 5 jobs\n[HYDRA] Launching 5 jobs locally\n[HYDRA] #0 : banana.x=4 banana.y=-1.484\n[__main__][INFO] - Banana_Function(x=4, y=-1.484)=30581.473\n[HYDRA] #1 : banana.x=3 banana.y=-3.653\n[__main__][INFO] - Banana_Function(x=3, y=-3.653)=16014.261\n[HYDRA] #2 : banana.x=0 banana.y=9.409\n[__main__][INFO] - Banana_Function(x=0, y=9.409)=8855.340\n[HYDRA] #3 : banana.x=-4 banana.y=2.059\n[__main__][INFO] - Banana_Function(x=-4, y=2.059)=19459.063\n[HYDRA] #4 : banana.x=-3 banana.y=-1.338\n[__main__][INFO] - Banana_Function(x=-3, y=-1.338)=10704.497\n[HYDRA] New best value: 8855.340, best parameters: {'banana.x': 0, 'banana.y': 9.409}\n")),(0,i.mdx)("p",null,"In this example, we set the range of ",(0,i.mdx)("inlineCode",{parentName:"p"},"x")," parameter as an integer in the interval ",(0,i.mdx)("inlineCode",{parentName:"p"},"[-5, 5]")," and the range of ",(0,i.mdx)("inlineCode",{parentName:"p"},"y")," parameter as a float in the interval ",(0,i.mdx)("inlineCode",{parentName:"p"},"[-5, 10.1]"),". Note that in the case of ",(0,i.mdx)("inlineCode",{parentName:"p"},"x"),", we used ",(0,i.mdx)("inlineCode",{parentName:"p"},"int(interval(...))")," and hence only integers are sampled. In the case of ",(0,i.mdx)("inlineCode",{parentName:"p"},"y"),", we used ",(0,i.mdx)("inlineCode",{parentName:"p"},"interval(...)")," which refers to a floating-point interval. Other supported formats are fixed parameters (e.g.",(0,i.mdx)("inlineCode",{parentName:"p"}," banana.x=5.0"),"), choice parameters (eg ",(0,i.mdx)("inlineCode",{parentName:"p"},"banana.x=choice(1,2,3)"),") and range (eg ",(0,i.mdx)("inlineCode",{parentName:"p"},"banana.x=range(1, 10)"),"). Note that ",(0,i.mdx)("inlineCode",{parentName:"p"},"interval"),", ",(0,i.mdx)("inlineCode",{parentName:"p"},"choice")," etc. are functions provided by Hydra, and you can read more about them ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.0/advanced/override_grammar/extended"},"here"),". An important thing to remember is, use ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.0/advanced/override_grammar/extended#interval-sweep"},(0,i.mdx)("inlineCode",{parentName:"a"},"interval"))," when we want Ax to sample values from an interval. ",(0,i.mdx)("a",{parentName:"p",href:"https://ax.dev/api/ax.html#ax.RangeParameter"},(0,i.mdx)("inlineCode",{parentName:"a"},"RangeParameter"))," in Ax is equivalent to ",(0,i.mdx)("inlineCode",{parentName:"p"},"interval")," in Hydra. Remember to use ",(0,i.mdx)("inlineCode",{parentName:"p"},"int(interval(...))")," if you want to sample only integer points from the interval. ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.0/advanced/override_grammar/extended#range-sweep"},(0,i.mdx)("inlineCode",{parentName:"a"},"range"))," can be used as an alternate way of specifying choice parameters. For example ",(0,i.mdx)("inlineCode",{parentName:"p"},"python example/banana.py -m banana.x=choice(1, 2, 3, 4)")," is equivalent to ",(0,i.mdx)("inlineCode",{parentName:"p"},"python example/banana.py -m banana.x=range(1, 5)"),"."),(0,i.mdx)("p",null,"The values of the ",(0,i.mdx)("inlineCode",{parentName:"p"},"x")," and ",(0,i.mdx)("inlineCode",{parentName:"p"},"y")," parameters can also be set using the config file ",(0,i.mdx)("inlineCode",{parentName:"p"},"plugins/hydra_ax_sweeper/example/conf/config.yaml"),". For instance, the configuration corresponding to the commandline arguments is as follows:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre"},"banana.x:\n type: range\n bounds: [-5, 5]\n\nbanana.y:\n type: range\n bounds: [-5, 10.1]\n")),(0,i.mdx)("p",null,"In general, the plugin supports setting all the Ax supported ",(0,i.mdx)("a",{parentName:"p",href:"https://ax.dev/api/core.html?highlight=range#module-ax.core.parameter"},"Parameters")," in the config. According to the ",(0,i.mdx)("a",{parentName:"p",href:"https://ax.dev/api/service.html#ax.service.ax_client.AxClient.create_experiment"},"Ax documentation"),", the required elements in the config are:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"name")," - Name of the parameter. It is of type string."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"type")," - Type of the parameter. It can take the following values: ",(0,i.mdx)("inlineCode",{parentName:"li"},"range"),", ",(0,i.mdx)("inlineCode",{parentName:"li"},"fixed"),", or ",(0,i.mdx)("inlineCode",{parentName:"li"},"choice"),"."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"bounds")," - Required only for the ",(0,i.mdx)("inlineCode",{parentName:"li"},"range")," parameters. It should be a list of two values, with the lower bound first."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"values")," - Required only for the ",(0,i.mdx)("inlineCode",{parentName:"li"},"choice")," parameters. It should be a list of values."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"value")," - Required only for the ",(0,i.mdx)("inlineCode",{parentName:"li"},"fixed")," parameters. It should be a single value. ")),(0,i.mdx)("p",null,"Note that if you want to sample integers in the range ",(0,i.mdx)("inlineCode",{parentName:"p"},"-5")," to ",(0,i.mdx)("inlineCode",{parentName:"p"},"5"),", you need to specify the range as ",(0,i.mdx)("inlineCode",{parentName:"p"},"int(interval(-5, 5))")," (in the command line) or ",(0,i.mdx)("inlineCode",{parentName:"p"},"[-5, 5]")," (in config). If you want to sample floats in range ",(0,i.mdx)("inlineCode",{parentName:"p"},"-5")," to ",(0,i.mdx)("inlineCode",{parentName:"p"},"5"),", you need to specify the range as ",(0,i.mdx)("inlineCode",{parentName:"p"},"interval(-5, 5)")," (in the command line) or ",(0,i.mdx)("inlineCode",{parentName:"p"},"[-5.0, 5.0]")," (in config)."),(0,i.mdx)("p",null,"The 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:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python your_app.py hydra/sweeper=ax --cfg hydra -p hydra.sweeper"',title:'"$',python:!0,"your_app.py":!0,"hydra/sweeper":"ax","--cfg":!0,hydra:!0,"-p":!0,'hydra.sweeper"':!0},"# @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 params: {}\n")))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/043fc566.fcbbec6b.js b/assets/js/043fc566.fcbbec6b.js new file mode 100644 index 0000000000..086763fc90 --- /dev/null +++ b/assets/js/043fc566.fcbbec6b.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[512],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>m,MDXProvider:()=>c,mdx:()=>h,useMDXComponents:()=>s,withMDXComponents:()=>d});var t=a(96540);function r(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(r[a]=e[a]);return r}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(r[a]=e[a])}return r}var m=t.createContext({}),d=function(e){return function(n){var a=s(n.components);return t.createElement(e,i({},n,{components:a}))}},s=function(e){var n=t.useContext(m),a=n;return e&&(a="function"==typeof e?e(n):p(p({},n),e)),a},c=function(e){var n=s(e.components);return t.createElement(m.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return t.createElement(t.Fragment,{},n)}},x=t.forwardRef((function(e,n){var a=e.components,r=e.mdxType,i=e.originalType,o=e.parentName,m=l(e,["components","mdxType","originalType","parentName"]),d=s(a),c=r,x=d["".concat(o,".").concat(c)]||d[c]||u[c]||i;return a?t.createElement(x,p(p({ref:n},m),{},{components:a})):t.createElement(x,p({ref:n},m))}));function h(e,n){var a=arguments,r=n&&n.mdxType;if("string"==typeof e||r){var i=a.length,o=new Array(i);o[0]=x;var p={};for(var l in n)hasOwnProperty.call(n,l)&&(p[l]=n[l]);p.originalType=e,p.mdxType="string"==typeof e?e:r,o[1]=p;for(var m=2;m{a.r(n),a.d(n,{contentTitle:()=>l,default:()=>c,frontMatter:()=>p,metadata:()=>m,toc:()=>d});var t=a(58168),r=a(98587),i=(a(96540),a(15680)),o=["components"],p={id:"ax_sweeper",title:"Ax Sweeper plugin",sidebar_label:"Ax Sweeper plugin"},l=void 0,m={unversionedId:"plugins/ax_sweeper",id:"version-1.0/plugins/ax_sweeper",title:"Ax Sweeper plugin",description:"PyPI",source:"@site/versioned_docs/version-1.0/plugins/ax_sweeper.md",sourceDirName:"plugins",slug:"/plugins/ax_sweeper",permalink:"/docs/1.0/plugins/ax_sweeper",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.0/plugins/ax_sweeper.md",tags:[],version:"1.0",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"ax_sweeper",title:"Ax Sweeper plugin",sidebar_label:"Ax Sweeper plugin"},sidebar:"version-1.0/docs",previous:{title:"Submitit Launcher plugin",permalink:"/docs/1.0/plugins/submitit_launcher"},next:{title:"Nevergrad Sweeper plugin",permalink:"/docs/1.0/plugins/nevergrad_sweeper"}},d=[{value:"Installation",id:"installation",children:[],level:3},{value:"Usage",id:"usage",children:[],level:3}],s={toc:d};function c(e){var n=e.components,a=(0,r.A)(e,o);return(0,i.mdx)("wrapper",(0,t.A)({},s,a,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,(0,i.mdx)("a",{parentName:"p",href:"https://img.shields.io/pypi/v/hydra-ax-sweeper"},(0,i.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/v/hydra-ax-sweeper",alt:"PyPI"})),"\n",(0,i.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/l/hydra-ax-sweeper",alt:"PyPI - License"}),"\n",(0,i.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/pyversions/hydra-ax-sweeper",alt:"PyPI - Python Version"}),"\n",(0,i.mdx)("a",{parentName:"p",href:"https://pypistats.org/packages/hydra-ax-sweeper"},(0,i.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/dm/hydra-ax-sweeper.svg",alt:"PyPI - Downloads"})),"\n",(0,i.mdx)("a",{parentName:"p",href:"https://github.com/facebookresearch/hydra/tree/1.0_branch/plugins/hydra_ax_sweeper/example"},(0,i.mdx)("img",{parentName:"a",src:"https://img.shields.io/badge/-Example%20application-informational",alt:"Example application"})),"\n",(0,i.mdx)("a",{parentName:"p",href:"https://github.com/facebookresearch/hydra/tree/1.0_branch/plugins/hydra_ax_sweeper"},(0,i.mdx)("img",{parentName:"a",src:"https://img.shields.io/badge/-Plugin%20source-informational",alt:"Plugin source"}))),(0,i.mdx)("p",null,"This plugin provides a mechanism for Hydra applications to use the ",(0,i.mdx)("a",{parentName:"p",href:"https://ax.dev/"},"Adaptive Experimentation Platform, aka Ax"),". Ax can optimize any experiment - machine learning experiments, A/B tests, and simulations. "),(0,i.mdx)("h3",{id:"installation"},"Installation"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"pip install hydra-ax-sweeper --upgrade\n")),(0,i.mdx)("h3",{id:"usage"},"Usage"),(0,i.mdx)("p",null,"Once installed, add ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra/sweeper=ax")," to your command line. Alternatively, override ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra/sweeper")," in your config:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - hydra/sweeper: ax\n")),(0,i.mdx)("p",null,"We include an example of how to use this plugin. The file ",(0,i.mdx)("a",{parentName:"p",href:"https://github.com/facebookresearch/hydra/blob/master/plugins/hydra_ax_sweeper/example/banana.py"},(0,i.mdx)("inlineCode",{parentName:"a"},"example/banana.py"))," implements the ",(0,i.mdx)("a",{parentName:"p",href:"https://en.wikipedia.org/wiki/Rosenbrock_function"},"Rosenbrock function (aka Banana function)"),". The return value of the function should be the value that we want to optimize."),(0,i.mdx)("p",null,"To compute the best parameters for the Banana function, clone the code and run the following command in the ",(0,i.mdx)("inlineCode",{parentName:"p"},"plugins/hydra_ax_sweeper")," directory:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre"},"python example/banana.py -m 'banana.x=int(interval(-5, 5))' 'banana.y=interval(-5, 10.1)'\n")),(0,i.mdx)("p",null,"The output of a run looks like:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre"},"[HYDRA] AxSweeper is optimizing the following parameters:\nbanana.x: range=[-5, 5], type = int\nbanana.y: range=[-5.0, 10.1], type = float\nax.modelbridge.dispatch_utils: Using Bayesian Optimization generation strategy: GenerationStrategy(name='Sobol+GPEI', steps=[Sobol for 5 arms, GPEI for subsequent arms], generated 0 arm(s) so far). Iterations after 5 will take longer to generate due to model-fitting.\nAxSweeper is launching 5 jobs\n[HYDRA] Launching 5 jobs locally\n[HYDRA] #0 : banana.x=4 banana.y=-1.484\n[__main__][INFO] - Banana_Function(x=4, y=-1.484)=30581.473\n[HYDRA] #1 : banana.x=3 banana.y=-3.653\n[__main__][INFO] - Banana_Function(x=3, y=-3.653)=16014.261\n[HYDRA] #2 : banana.x=0 banana.y=9.409\n[__main__][INFO] - Banana_Function(x=0, y=9.409)=8855.340\n[HYDRA] #3 : banana.x=-4 banana.y=2.059\n[__main__][INFO] - Banana_Function(x=-4, y=2.059)=19459.063\n[HYDRA] #4 : banana.x=-3 banana.y=-1.338\n[__main__][INFO] - Banana_Function(x=-3, y=-1.338)=10704.497\n[HYDRA] New best value: 8855.340, best parameters: {'banana.x': 0, 'banana.y': 9.409}\n")),(0,i.mdx)("p",null,"In this example, we set the range of ",(0,i.mdx)("inlineCode",{parentName:"p"},"x")," parameter as an integer in the interval ",(0,i.mdx)("inlineCode",{parentName:"p"},"[-5, 5]")," and the range of ",(0,i.mdx)("inlineCode",{parentName:"p"},"y")," parameter as a float in the interval ",(0,i.mdx)("inlineCode",{parentName:"p"},"[-5, 10.1]"),". Note that in the case of ",(0,i.mdx)("inlineCode",{parentName:"p"},"x"),", we used ",(0,i.mdx)("inlineCode",{parentName:"p"},"int(interval(...))")," and hence only integers are sampled. In the case of ",(0,i.mdx)("inlineCode",{parentName:"p"},"y"),", we used ",(0,i.mdx)("inlineCode",{parentName:"p"},"interval(...)")," which refers to a floating-point interval. Other supported formats are fixed parameters (e.g.",(0,i.mdx)("inlineCode",{parentName:"p"}," banana.x=5.0"),"), choice parameters (eg ",(0,i.mdx)("inlineCode",{parentName:"p"},"banana.x=choice(1,2,3)"),") and range (eg ",(0,i.mdx)("inlineCode",{parentName:"p"},"banana.x=range(1, 10)"),"). Note that ",(0,i.mdx)("inlineCode",{parentName:"p"},"interval"),", ",(0,i.mdx)("inlineCode",{parentName:"p"},"choice")," etc. are functions provided by Hydra, and you can read more about them ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.0/advanced/override_grammar/extended"},"here"),". An important thing to remember is, use ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.0/advanced/override_grammar/extended#interval-sweep"},(0,i.mdx)("inlineCode",{parentName:"a"},"interval"))," when we want Ax to sample values from an interval. ",(0,i.mdx)("a",{parentName:"p",href:"https://ax.dev/api/ax.html#ax.RangeParameter"},(0,i.mdx)("inlineCode",{parentName:"a"},"RangeParameter"))," in Ax is equivalent to ",(0,i.mdx)("inlineCode",{parentName:"p"},"interval")," in Hydra. Remember to use ",(0,i.mdx)("inlineCode",{parentName:"p"},"int(interval(...))")," if you want to sample only integer points from the interval. ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.0/advanced/override_grammar/extended#range-sweep"},(0,i.mdx)("inlineCode",{parentName:"a"},"range"))," can be used as an alternate way of specifying choice parameters. For example ",(0,i.mdx)("inlineCode",{parentName:"p"},"python example/banana.py -m banana.x=choice(1, 2, 3, 4)")," is equivalent to ",(0,i.mdx)("inlineCode",{parentName:"p"},"python example/banana.py -m banana.x=range(1, 5)"),"."),(0,i.mdx)("p",null,"The values of the ",(0,i.mdx)("inlineCode",{parentName:"p"},"x")," and ",(0,i.mdx)("inlineCode",{parentName:"p"},"y")," parameters can also be set using the config file ",(0,i.mdx)("inlineCode",{parentName:"p"},"plugins/hydra_ax_sweeper/example/conf/config.yaml"),". For instance, the configuration corresponding to the commandline arguments is as follows:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre"},"banana.x:\n type: range\n bounds: [-5, 5]\n\nbanana.y:\n type: range\n bounds: [-5, 10.1]\n")),(0,i.mdx)("p",null,"In general, the plugin supports setting all the Ax supported ",(0,i.mdx)("a",{parentName:"p",href:"https://ax.dev/api/core.html?highlight=range#module-ax.core.parameter"},"Parameters")," in the config. According to the ",(0,i.mdx)("a",{parentName:"p",href:"https://ax.dev/api/service.html#ax.service.ax_client.AxClient.create_experiment"},"Ax documentation"),", the required elements in the config are:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"name")," - Name of the parameter. It is of type string."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"type")," - Type of the parameter. It can take the following values: ",(0,i.mdx)("inlineCode",{parentName:"li"},"range"),", ",(0,i.mdx)("inlineCode",{parentName:"li"},"fixed"),", or ",(0,i.mdx)("inlineCode",{parentName:"li"},"choice"),"."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"bounds")," - Required only for the ",(0,i.mdx)("inlineCode",{parentName:"li"},"range")," parameters. It should be a list of two values, with the lower bound first."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"values")," - Required only for the ",(0,i.mdx)("inlineCode",{parentName:"li"},"choice")," parameters. It should be a list of values."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"value")," - Required only for the ",(0,i.mdx)("inlineCode",{parentName:"li"},"fixed")," parameters. It should be a single value. ")),(0,i.mdx)("p",null,"Note that if you want to sample integers in the range ",(0,i.mdx)("inlineCode",{parentName:"p"},"-5")," to ",(0,i.mdx)("inlineCode",{parentName:"p"},"5"),", you need to specify the range as ",(0,i.mdx)("inlineCode",{parentName:"p"},"int(interval(-5, 5))")," (in the command line) or ",(0,i.mdx)("inlineCode",{parentName:"p"},"[-5, 5]")," (in config). If you want to sample floats in range ",(0,i.mdx)("inlineCode",{parentName:"p"},"-5")," to ",(0,i.mdx)("inlineCode",{parentName:"p"},"5"),", you need to specify the range as ",(0,i.mdx)("inlineCode",{parentName:"p"},"interval(-5, 5)")," (in the command line) or ",(0,i.mdx)("inlineCode",{parentName:"p"},"[-5.0, 5.0]")," (in config)."),(0,i.mdx)("p",null,"The 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:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python your_app.py hydra/sweeper=ax --cfg hydra -p hydra.sweeper"',title:'"$',python:!0,"your_app.py":!0,"hydra/sweeper":"ax","--cfg":!0,hydra:!0,"-p":!0,'hydra.sweeper"':!0},"# @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 params: {}\n")))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/05d1ea85.c9a1498c.js b/assets/js/05d1ea85.c9a1498c.js new file mode 100644 index 0000000000..264ad88667 --- /dev/null +++ b/assets/js/05d1ea85.c9a1498c.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[5196],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>d,MDXProvider:()=>c,mdx:()=>f,useMDXComponents:()=>p,withMDXComponents:()=>m});var a=t(96540);function i(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function r(){return r=Object.assign||function(e){for(var n=1;n=0||(i[t]=e[t]);return i}(e,n);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(i[t]=e[t])}return i}var d=a.createContext({}),m=function(e){return function(n){var t=p(n.components);return a.createElement(e,r({},n,{components:t}))}},p=function(e){var n=a.useContext(d),t=n;return e&&(t="function"==typeof e?e(n):s(s({},n),e)),t},c=function(e){var n=p(e.components);return a.createElement(d.Provider,{value:n},e.children)},g={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},u=a.forwardRef((function(e,n){var t=e.components,i=e.mdxType,r=e.originalType,o=e.parentName,d=l(e,["components","mdxType","originalType","parentName"]),m=p(t),c=i,u=m["".concat(o,".").concat(c)]||m[c]||g[c]||r;return t?a.createElement(u,s(s({ref:n},d),{},{components:t})):a.createElement(u,s({ref:n},d))}));function f(e,n){var t=arguments,i=n&&n.mdxType;if("string"==typeof e||i){var r=t.length,o=new Array(r);o[0]=u;var s={};for(var l in n)hasOwnProperty.call(n,l)&&(s[l]=n[l]);s.originalType=e,s.mdxType="string"==typeof e?e:i,o[1]=s;for(var d=2;d{t.d(n,{A:()=>l,C:()=>d});var a=t(58168),i=t(96540),r=t(75489),o=t(44586),s=t(74098);function l(e){return i.createElement(r.default,(0,a.A)({},e,{to:(n=e.to,l=(0,s.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==l?void 0:l.name)?t:"current"]+n),target:"_blank"}));var n,t,l}function d(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return i.createElement(l,e,i.createElement("span",null,"\xa0"),i.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},17428:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>d,default:()=>g,frontMatter:()=>l,metadata:()=>m,toc:()=>p});var a=t(58168),i=t(98587),r=(t(96540),t(15680)),o=t(49595),s=["components"],l={id:"overview",title:"Instantiating objects with Hydra",sidebar_label:"Overview"},d=void 0,m={unversionedId:"advanced/instantiate_objects/overview",id:"version-1.1/advanced/instantiate_objects/overview",title:"Instantiating objects with Hydra",description:"One of the best ways to drive different behavior in an application is to instantiate different implementations of an interface.",source:"@site/versioned_docs/version-1.1/advanced/instantiate_objects/overview.md",sourceDirName:"advanced/instantiate_objects",slug:"/advanced/instantiate_objects/overview",permalink:"/docs/1.1/advanced/instantiate_objects/overview",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/advanced/instantiate_objects/overview.md",tags:[],version:"1.1",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"overview",title:"Instantiating objects with Hydra",sidebar_label:"Overview"},sidebar:"version-1.1/docs",previous:{title:"Packages",permalink:"/docs/1.1/advanced/overriding_packages"},next:{title:"Config files example",permalink:"/docs/1.1/advanced/instantiate_objects/config_files"}},p=[{value:"Simple usage",id:"simple-usage",children:[],level:3},{value:"Recursive instantiation",id:"recursive-instantiation",children:[],level:3},{value:"Disable recursive instantiation",id:"disable-recursive-instantiation",children:[],level:3},{value:"Parameter conversion strategies",id:"parameter-conversion-strategies",children:[{value:"Partial Instantiation (for Hydra version >= 1.1.2)",id:"partial-instantiation-for-hydra-version--112",children:[],level:3},{value:"Instantiation of builtins",id:"instantiation-of-builtins",children:[],level:3}],level:2}],c={toc:p};function g(e){var n=e.components,t=(0,i.A)(e,s);return(0,r.mdx)("wrapper",(0,a.A)({},c,t,{components:n,mdxType:"MDXLayout"}),(0,r.mdx)(o.C,{text:"Example applications",to:"examples/instantiate",mdxType:"ExampleGithubLink"}),(0,r.mdx)("p",null,"One of the best ways to drive different behavior in an application is to instantiate different implementations of an interface.\nThe code using the instantiated object only knows the interface which remains constant, but the behavior\nis determined by the actual object instance."),(0,r.mdx)("p",null,"Hydra provides ",(0,r.mdx)("inlineCode",{parentName:"p"},"hydra.utils.instantiate()")," (and its alias ",(0,r.mdx)("inlineCode",{parentName:"p"},"hydra.utils.call()"),") for instantiating objects and calling functions. Prefer ",(0,r.mdx)("inlineCode",{parentName:"p"},"instantiate")," for creating objects and ",(0,r.mdx)("inlineCode",{parentName:"p"},"call")," for invoking functions."),(0,r.mdx)("p",null,"Call/instantiate supports:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Constructing an object by calling the ",(0,r.mdx)("inlineCode",{parentName:"li"},"__init__")," method"),(0,r.mdx)("li",{parentName:"ul"},"Calling functions, static functions, class methods and other callable global objects")),(0,r.mdx)("details",null,(0,r.mdx)("summary",null,"Instantiate API (Expand for details)"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},'def instantiate(config: Any, *args: Any, **kwargs: Any) -> Any:\n """\n :param config: An config object describing what to call and what params to use.\n In addition to the parameters, the config must contain:\n _target_ : target class or callable name (str)\n And may contain:\n _args_: List-like of positional arguments to pass to the target\n _recursive_: Construct nested objects as well (bool).\n True by default.\n may be overridden via a _recursive_ key in\n the kwargs\n _convert_: Conversion strategy\n none : Passed objects are DictConfig and ListConfig, default\n partial : Passed objects are converted to dict and list, with\n the exception of Structured Configs (and their fields).\n all : Passed objects are dicts, lists and primitives without\n a trace of OmegaConf containers\n :param args: Optional positional parameters pass-through\n :param kwargs: Optional named parameters to override\n parameters in the config object. Parameters not present\n in the config objects are being passed as is to the target.\n IMPORTANT: dataclasses instances in kwargs are interpreted as config\n and cannot be used as passthrough\n :return: if _target_ is a class name: the instantiated object\n if _target_ is a callable: the return value of the call\n """\n\n# Alias for instantiate\ncall = instantiate\n'))),(0,r.mdx)("br",null),(0,r.mdx)("p",null,"The config passed to these functions must have a key called ",(0,r.mdx)("inlineCode",{parentName:"p"},"_target_"),", with the value of a fully qualified class name, class method, static method or callable.\nFor convenience, ",(0,r.mdx)("inlineCode",{parentName:"p"},"None")," config results in a ",(0,r.mdx)("inlineCode",{parentName:"p"},"None")," object."),(0,r.mdx)("p",null,(0,r.mdx)("strong",{parentName:"p"},"Named arguments")," : Config fields (except reserved fields like ",(0,r.mdx)("inlineCode",{parentName:"p"},"_target_"),") are passed as named arguments to the target.\nNamed arguments in the config can be overridden by passing named argument with the same name in the ",(0,r.mdx)("inlineCode",{parentName:"p"},"instantiate()")," call-site."),(0,r.mdx)("p",null,(0,r.mdx)("strong",{parentName:"p"},"Positional arguments")," : The config may contain a ",(0,r.mdx)("inlineCode",{parentName:"p"},"_args_")," field representing positional arguments to pass to the target.\nThe positional arguments can be overridden together by passing positional arguments in the ",(0,r.mdx)("inlineCode",{parentName:"p"},"instantiate()")," call-site."),(0,r.mdx)("h3",{id:"simple-usage"},"Simple usage"),(0,r.mdx)("p",null,"Your application might have an Optimizer class:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Example class"',title:'"Example','class"':!0},"class Optimizer:\n algo: str\n lr: float\n\n def __init__(self, algo: str, lr: float) -> None:\n self.algo = algo\n self.lr = lr\n")),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Config"',title:'"Config"'},"optimizer:\n _target_: my_app.Optimizer\n algo: SGD\n lr: 0.01\n\n\n\n\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Instantiation"',title:'"Instantiation"'},"opt = instantiate(cfg.optimizer)\nprint(opt)\n# Optimizer(algo=SGD,lr=0.01)\n\n# override parameters on the call-site\nopt = instantiate(cfg.optimizer, lr=0.2)\nprint(opt)\n# Optimizer(algo=SGD,lr=0.2)\n")))),(0,r.mdx)("h3",{id:"recursive-instantiation"},"Recursive instantiation"),(0,r.mdx)("p",null,"Let's add a Dataset and a Trainer class. The trainer holds a Dataset and an Optimizer instances."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Additional classes"',title:'"Additional','classes"':!0},"class Dataset:\n name: str\n path: str\n\n def __init__(self, name: str, path: str) -> None:\n self.name = name\n self.path = path\n\n\nclass Trainer:\n def __init__(self, optimizer: Optimizer, dataset: Dataset) -> None:\n self.optimizer = optimizer\n self.dataset = dataset\n")),(0,r.mdx)("p",null,"With the following config, you can instantiate the whole thing with a single call:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Example config"',title:'"Example','config"':!0},"trainer:\n _target_: my_app.Trainer\n optimizer:\n _target_: my_app.Optimizer\n algo: SGD\n lr: 0.01\n dataset:\n _target_: my_app.Dataset\n name: Imagenet\n path: /datasets/imagenet\n")),(0,r.mdx)("p",null,"Hydra will instantiate nested objects recursively by default."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},"trainer = instantiate(cfg.trainer)\nprint(trainer)\n# Trainer(\n# optimizer=Optimizer(algo=SGD,lr=0.01),\n# dataset=Dataset(name=Imagenet, path=/datasets/imagenet)\n# )\n")),(0,r.mdx)("p",null,"You can override parameters for nested objects:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},'trainer = instantiate(\n cfg.trainer,\n optimizer={"lr": 0.3},\n dataset={"name": "cifar10", "path": "/datasets/cifar10"},\n)\nprint(trainer)\n# Trainer(\n# optimizer=Optimizer(algo=SGD,lr=0.3),\n# dataset=Dataset(name=cifar10, path=/datasets/cifar10)\n# )\n')),(0,r.mdx)("p",null,"Similarly, positional arguments of nested objects can be overridden:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},'obj = instantiate(\n cfg.object,\n # pass 1 and 2 as positional arguments to the target object\n 1, 2, \n # pass 3 and 4 as positional arguments to a nested child object\n child={"_args_": [3, 4]},\n)\n')),(0,r.mdx)("h3",{id:"disable-recursive-instantiation"},"Disable recursive instantiation"),(0,r.mdx)("p",null,"You can disable recursive instantiation by setting ",(0,r.mdx)("inlineCode",{parentName:"p"},"_recursive_")," to ",(0,r.mdx)("inlineCode",{parentName:"p"},"False")," in the config node or in the call-site\nIn that case the Trainer object will receive an OmegaConf DictConfig for nested dataset and optimizer instead of the instantiated objects."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},"optimizer = instantiate(cfg.trainer, _recursive_=False)\nprint(optimizer)\n")),(0,r.mdx)("p",null,"Output:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},"Trainer(\n optimizer={\n '_target_': 'my_app.Optimizer', 'algo': 'SGD', 'lr': 0.01\n },\n dataset={\n '_target_': 'my_app.Dataset', 'name': 'Imagenet', 'path': '/datasets/imagenet'\n }\n)\n")),(0,r.mdx)("h2",{id:"parameter-conversion-strategies"},"Parameter conversion strategies"),(0,r.mdx)("p",null,"By default, the parameters passed to the target are either primitives (int,\nfloat, bool etc) or OmegaConf containers (",(0,r.mdx)("inlineCode",{parentName:"p"},"DictConfig"),", ",(0,r.mdx)("inlineCode",{parentName:"p"},"ListConfig"),").\nOmegaConf containers have many advantages over primitive dicts and lists,\nincluding convenient attribute access for keys,\n",(0,r.mdx)("a",{parentName:"p",href:"https://omegaconf.readthedocs.io/en/latest/structured_config.html"},"duck-typing as instances of dataclasses or attrs classes"),", and\nsupport for ",(0,r.mdx)("a",{parentName:"p",href:"https://omegaconf.readthedocs.io/en/latest/usage.html#variable-interpolation"},"variable interpolation"),"\nand ",(0,r.mdx)("a",{parentName:"p",href:"https://omegaconf.readthedocs.io/en/latest/custom_resolvers.html"},"custom resolvers"),".\nIf the callable targeted by ",(0,r.mdx)("inlineCode",{parentName:"p"},"instantiate")," leverages OmegaConf's features, it\nwill make sense to pass ",(0,r.mdx)("inlineCode",{parentName:"p"},"DictConfig")," and ",(0,r.mdx)("inlineCode",{parentName:"p"},"ListConfig")," instances directly to\nthat callable."),(0,r.mdx)("p",null,"That being said, in many cases it's desired to pass normal Python dicts and\nlists, rather than ",(0,r.mdx)("inlineCode",{parentName:"p"},"DictConfig")," or ",(0,r.mdx)("inlineCode",{parentName:"p"},"ListConfig")," instances, as arguments to your\ncallable. You can change instantiate's argument conversion strategy using the\n",(0,r.mdx)("inlineCode",{parentName:"p"},"_convert_")," parameter. Supported values are:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},'"none"')," : Default behavior, Use OmegaConf containers"),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},'"partial"')," : Convert OmegaConf containers to dict and list, except Structured Configs."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},'"all"')," : Convert everything to primitive containers")),(0,r.mdx)("p",null,"The conversion strategy applies recursively to all subconfigs of the instantiation target.\nHere is an example demonstrating the various conversion strategies:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},'from dataclasses import dataclass\nfrom omegaconf import DictConfig, OmegaConf\nfrom hydra.utils import instantiate\n\n@dataclass\nclass Foo:\n a: int = 123\n\nclass MyTarget:\n def __init__(self, foo, bar):\n self.foo = foo\n self.bar = bar\n\ncfg = OmegaConf.create(\n {\n "_target_": "__main__.MyTarget",\n "foo": Foo(),\n "bar": {"b": 456},\n }\n)\n\nobj_none = instantiate(cfg, _convert_="none")\nassert isinstance(obj_none, MyTarget)\nassert isinstance(obj_none.foo, DictConfig)\nassert isinstance(obj_none.bar, DictConfig)\n\nobj_partial = instantiate(cfg, _convert_="partial")\nassert isinstance(obj_partial, MyTarget)\nassert isinstance(obj_partial.foo, DictConfig)\nassert isinstance(obj_partial.bar, dict)\n\nobj_all = instantiate(cfg, _convert_="all")\nassert isinstance(obj_none, MyTarget)\nassert isinstance(obj_all.foo, dict)\nassert isinstance(obj_all.bar, dict)\n')),(0,r.mdx)("p",null,"Passing the ",(0,r.mdx)("inlineCode",{parentName:"p"},"_convert_")," keyword argument to ",(0,r.mdx)("inlineCode",{parentName:"p"},"instantiate")," has the same effect as defining\na ",(0,r.mdx)("inlineCode",{parentName:"p"},"_convert_")," attribute on your config object. Here is an example creating\ninstances of ",(0,r.mdx)("inlineCode",{parentName:"p"},"MyTarget")," that are equivalent to the above:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},'cfg_none = OmegaConf.create({..., "_convert_": "none"})\nobj_none = instantiate(cfg_none)\n\ncfg_partial = OmegaConf.create({..., "_convert_": "partial"})\nobj_partial = instantiate(cfg_partial)\n\ncfg_all = OmegaConf.create({..., "_convert_": "all"})\nobj_all = instantiate(cfg_all)\n')),(0,r.mdx)("h3",{id:"partial-instantiation-for-hydra-version--112"},"Partial Instantiation (for Hydra version >= 1.1.2)"),(0,r.mdx)("p",null,"Sometimes you may not set all parameters needed to instantiate an object from the configuration, in this case you can set\n",(0,r.mdx)("inlineCode",{parentName:"p"},"_partial_")," to be ",(0,r.mdx)("inlineCode",{parentName:"p"},"True")," to get a ",(0,r.mdx)("inlineCode",{parentName:"p"},"functools.partial")," wrapped object or method, then complete initializing the object in\nthe application code. Here is an example:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Example classes"',title:'"Example','classes"':!0},'class Optimizer:\n algo: str\n lr: float\n\n def __init__(self, algo: str, lr: float) -> None:\n self.algo = algo\n self.lr = lr\n\n def __repr__(self) -> str:\n return f"Optimizer(algo={self.algo},lr={self.lr})"\n\n\nclass Model:\n def __init__(self, optim_partial: Any, lr: float):\n super().__init__()\n self.optim = optim_partial(lr=lr)\n self.lr = lr\n\n def __repr__(self) -> str:\n return f"Model(Optimizer={self.optim},lr={self.lr})"\n')),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--5"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Config"',title:'"Config"'},"model:\n _target_: my_app.Model\n optim_partial:\n _partial_: true\n _target_: my_app.Optimizer\n algo: SGD\n lr: 0.01\n"))),(0,r.mdx)("div",{className:"col col--7"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Instantiation"',title:'"Instantiation"'},'model = instantiate(cfg.model)\nprint(model)\n# "Model(Optimizer=Optimizer(algo=SGD,lr=0.01),lr=0.01)\n')))),(0,r.mdx)("p",null,"If you are repeatedly instantiating the same config,\nusing ",(0,r.mdx)("inlineCode",{parentName:"p"},"_partial_=True")," may provide a significant speedup as compared with regular (non-partial) instantiation."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},"factory = instantiate(config, _partial_=True)\nobj = factory()\n")),(0,r.mdx)("p",null,"In the above example, repeatedly calling ",(0,r.mdx)("inlineCode",{parentName:"p"},"factory")," would be faster than repeatedly calling ",(0,r.mdx)("inlineCode",{parentName:"p"},"instantiate(config)"),".\nA caveat of this approach is that the same keyword arguments would be re-used in each call to ",(0,r.mdx)("inlineCode",{parentName:"p"},"factory"),"."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},'class Foo:\n ...\n\nclass Bar:\n def __init__(self, foo):\n self.foo = foo\n\nbar_conf = {\n "_target_": "__main__.Bar",\n "foo": {"_target_": "__main__.Foo"},\n}\n\nbar_factory = instantiate(bar_conf, _partial_=True)\nbar1 = bar_factory()\nbar2 = bar_factory()\n\nassert bar1 is not bar2\nassert bar1.foo is bar2.foo # the `Foo` instance is re-used here\n')),(0,r.mdx)("p",null,"This does not apply if ",(0,r.mdx)("inlineCode",{parentName:"p"},"_partial_=False"),",\nin which case a new ",(0,r.mdx)("inlineCode",{parentName:"p"},"Foo")," instance would be created with each call to ",(0,r.mdx)("inlineCode",{parentName:"p"},"instantiate"),"."),(0,r.mdx)("h3",{id:"instantiation-of-builtins"},"Instantiation of builtins"),(0,r.mdx)("p",null,"The value of ",(0,r.mdx)("inlineCode",{parentName:"p"},"_target_")," passed to ",(0,r.mdx)("inlineCode",{parentName:"p"},"instantiate"),' should be a "dotpath" pointing\nto some callable that can be looked up via a combination of ',(0,r.mdx)("inlineCode",{parentName:"p"},"import")," and ",(0,r.mdx)("inlineCode",{parentName:"p"},"getattr"),".\nIf you want to target one of Python's ",(0,r.mdx)("a",{parentName:"p",href:"https://docs.python.org/3/library/functions.html"},"built-in functions")," (such as ",(0,r.mdx)("inlineCode",{parentName:"p"},"len")," or ",(0,r.mdx)("inlineCode",{parentName:"p"},"print")," or ",(0,r.mdx)("inlineCode",{parentName:"p"},"divmod"),"),\nyou will need to provide a dotpath looking up that function in Python's ",(0,r.mdx)("a",{parentName:"p",href:"https://docs.python.org/3/library/builtins.html"},(0,r.mdx)("inlineCode",{parentName:"a"},"builtins"))," module."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},'from hydra.utils import instantiate\n# instantiate({"_target_": "len"}, [1,2,3]) # this gives an InstantiationException\ninstantiate({"_target_": "builtins.len"}, [1,2,3]) # this works, returns the number 3\n')))}g.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/05d1ea85.e1b52c0c.js b/assets/js/05d1ea85.e1b52c0c.js deleted file mode 100644 index ccba1d7f4c..0000000000 --- a/assets/js/05d1ea85.e1b52c0c.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[5196],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>d,MDXProvider:()=>c,mdx:()=>f,useMDXComponents:()=>p,withMDXComponents:()=>m});var a=t(96540);function i(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function r(){return r=Object.assign||function(e){for(var n=1;n=0||(i[t]=e[t]);return i}(e,n);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(i[t]=e[t])}return i}var d=a.createContext({}),m=function(e){return function(n){var t=p(n.components);return a.createElement(e,r({},n,{components:t}))}},p=function(e){var n=a.useContext(d),t=n;return e&&(t="function"==typeof e?e(n):s(s({},n),e)),t},c=function(e){var n=p(e.components);return a.createElement(d.Provider,{value:n},e.children)},g={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},u=a.forwardRef((function(e,n){var t=e.components,i=e.mdxType,r=e.originalType,o=e.parentName,d=l(e,["components","mdxType","originalType","parentName"]),m=p(t),c=i,u=m["".concat(o,".").concat(c)]||m[c]||g[c]||r;return t?a.createElement(u,s(s({ref:n},d),{},{components:t})):a.createElement(u,s({ref:n},d))}));function f(e,n){var t=arguments,i=n&&n.mdxType;if("string"==typeof e||i){var r=t.length,o=new Array(r);o[0]=u;var s={};for(var l in n)hasOwnProperty.call(n,l)&&(s[l]=n[l]);s.originalType=e,s.mdxType="string"==typeof e?e:i,o[1]=s;for(var d=2;d{t.d(n,{A:()=>l,C:()=>d});var a=t(58168),i=t(96540),r=t(75489),o=t(44586),s=t(74098);function l(e){return i.createElement(r.default,(0,a.A)({},e,{to:(n=e.to,l=(0,s.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==l?void 0:l.name)?t:"current"]+n),target:"_blank"}));var n,t,l}function d(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return i.createElement(l,e,i.createElement("span",null,"\xa0"),i.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},17428:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>d,default:()=>g,frontMatter:()=>l,metadata:()=>m,toc:()=>p});var a=t(58168),i=t(98587),r=(t(96540),t(15680)),o=t(49595),s=["components"],l={id:"overview",title:"Instantiating objects with Hydra",sidebar_label:"Overview"},d=void 0,m={unversionedId:"advanced/instantiate_objects/overview",id:"version-1.1/advanced/instantiate_objects/overview",title:"Instantiating objects with Hydra",description:"One of the best ways to drive different behavior in an application is to instantiate different implementations of an interface.",source:"@site/versioned_docs/version-1.1/advanced/instantiate_objects/overview.md",sourceDirName:"advanced/instantiate_objects",slug:"/advanced/instantiate_objects/overview",permalink:"/docs/1.1/advanced/instantiate_objects/overview",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/advanced/instantiate_objects/overview.md",tags:[],version:"1.1",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"overview",title:"Instantiating objects with Hydra",sidebar_label:"Overview"},sidebar:"version-1.1/docs",previous:{title:"Packages",permalink:"/docs/1.1/advanced/overriding_packages"},next:{title:"Config files example",permalink:"/docs/1.1/advanced/instantiate_objects/config_files"}},p=[{value:"Simple usage",id:"simple-usage",children:[],level:3},{value:"Recursive instantiation",id:"recursive-instantiation",children:[],level:3},{value:"Disable recursive instantiation",id:"disable-recursive-instantiation",children:[],level:3},{value:"Parameter conversion strategies",id:"parameter-conversion-strategies",children:[{value:"Partial Instantiation (for Hydra version >= 1.1.2)",id:"partial-instantiation-for-hydra-version--112",children:[],level:3},{value:"Instantiation of builtins",id:"instantiation-of-builtins",children:[],level:3}],level:2}],c={toc:p};function g(e){var n=e.components,t=(0,i.A)(e,s);return(0,r.mdx)("wrapper",(0,a.A)({},c,t,{components:n,mdxType:"MDXLayout"}),(0,r.mdx)(o.C,{text:"Example applications",to:"examples/instantiate",mdxType:"ExampleGithubLink"}),(0,r.mdx)("p",null,"One of the best ways to drive different behavior in an application is to instantiate different implementations of an interface.\nThe code using the instantiated object only knows the interface which remains constant, but the behavior\nis determined by the actual object instance."),(0,r.mdx)("p",null,"Hydra provides ",(0,r.mdx)("inlineCode",{parentName:"p"},"hydra.utils.instantiate()")," (and its alias ",(0,r.mdx)("inlineCode",{parentName:"p"},"hydra.utils.call()"),") for instantiating objects and calling functions. Prefer ",(0,r.mdx)("inlineCode",{parentName:"p"},"instantiate")," for creating objects and ",(0,r.mdx)("inlineCode",{parentName:"p"},"call")," for invoking functions."),(0,r.mdx)("p",null,"Call/instantiate supports:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Constructing an object by calling the ",(0,r.mdx)("inlineCode",{parentName:"li"},"__init__")," method"),(0,r.mdx)("li",{parentName:"ul"},"Calling functions, static functions, class methods and other callable global objects")),(0,r.mdx)("details",null,(0,r.mdx)("summary",null,"Instantiate API (Expand for details)"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},'def instantiate(config: Any, *args: Any, **kwargs: Any) -> Any:\n """\n :param config: An config object describing what to call and what params to use.\n In addition to the parameters, the config must contain:\n _target_ : target class or callable name (str)\n And may contain:\n _args_: List-like of positional arguments to pass to the target\n _recursive_: Construct nested objects as well (bool).\n True by default.\n may be overridden via a _recursive_ key in\n the kwargs\n _convert_: Conversion strategy\n none : Passed objects are DictConfig and ListConfig, default\n partial : Passed objects are converted to dict and list, with\n the exception of Structured Configs (and their fields).\n all : Passed objects are dicts, lists and primitives without\n a trace of OmegaConf containers\n :param args: Optional positional parameters pass-through\n :param kwargs: Optional named parameters to override\n parameters in the config object. Parameters not present\n in the config objects are being passed as is to the target.\n IMPORTANT: dataclasses instances in kwargs are interpreted as config\n and cannot be used as passthrough\n :return: if _target_ is a class name: the instantiated object\n if _target_ is a callable: the return value of the call\n """\n\n# Alias for instantiate\ncall = instantiate\n'))),(0,r.mdx)("br",null),(0,r.mdx)("p",null,"The config passed to these functions must have a key called ",(0,r.mdx)("inlineCode",{parentName:"p"},"_target_"),", with the value of a fully qualified class name, class method, static method or callable.\nFor convenience, ",(0,r.mdx)("inlineCode",{parentName:"p"},"None")," config results in a ",(0,r.mdx)("inlineCode",{parentName:"p"},"None")," object."),(0,r.mdx)("p",null,(0,r.mdx)("strong",{parentName:"p"},"Named arguments")," : Config fields (except reserved fields like ",(0,r.mdx)("inlineCode",{parentName:"p"},"_target_"),") are passed as named arguments to the target.\nNamed arguments in the config can be overridden by passing named argument with the same name in the ",(0,r.mdx)("inlineCode",{parentName:"p"},"instantiate()")," call-site."),(0,r.mdx)("p",null,(0,r.mdx)("strong",{parentName:"p"},"Positional arguments")," : The config may contain a ",(0,r.mdx)("inlineCode",{parentName:"p"},"_args_")," field representing positional arguments to pass to the target.\nThe positional arguments can be overridden together by passing positional arguments in the ",(0,r.mdx)("inlineCode",{parentName:"p"},"instantiate()")," call-site."),(0,r.mdx)("h3",{id:"simple-usage"},"Simple usage"),(0,r.mdx)("p",null,"Your application might have an Optimizer class:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Example class"',title:'"Example','class"':!0},"class Optimizer:\n algo: str\n lr: float\n\n def __init__(self, algo: str, lr: float) -> None:\n self.algo = algo\n self.lr = lr\n")),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Config"',title:'"Config"'},"optimizer:\n _target_: my_app.Optimizer\n algo: SGD\n lr: 0.01\n\n\n\n\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Instantiation"',title:'"Instantiation"'},"opt = instantiate(cfg.optimizer)\nprint(opt)\n# Optimizer(algo=SGD,lr=0.01)\n\n# override parameters on the call-site\nopt = instantiate(cfg.optimizer, lr=0.2)\nprint(opt)\n# Optimizer(algo=SGD,lr=0.2)\n")))),(0,r.mdx)("h3",{id:"recursive-instantiation"},"Recursive instantiation"),(0,r.mdx)("p",null,"Let's add a Dataset and a Trainer class. The trainer holds a Dataset and an Optimizer instances."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Additional classes"',title:'"Additional','classes"':!0},"class Dataset:\n name: str\n path: str\n\n def __init__(self, name: str, path: str) -> None:\n self.name = name\n self.path = path\n\n\nclass Trainer:\n def __init__(self, optimizer: Optimizer, dataset: Dataset) -> None:\n self.optimizer = optimizer\n self.dataset = dataset\n")),(0,r.mdx)("p",null,"With the following config, you can instantiate the whole thing with a single call:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Example config"',title:'"Example','config"':!0},"trainer:\n _target_: my_app.Trainer\n optimizer:\n _target_: my_app.Optimizer\n algo: SGD\n lr: 0.01\n dataset:\n _target_: my_app.Dataset\n name: Imagenet\n path: /datasets/imagenet\n")),(0,r.mdx)("p",null,"Hydra will instantiate nested objects recursively by default."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},"trainer = instantiate(cfg.trainer)\nprint(trainer)\n# Trainer(\n# optimizer=Optimizer(algo=SGD,lr=0.01),\n# dataset=Dataset(name=Imagenet, path=/datasets/imagenet)\n# )\n")),(0,r.mdx)("p",null,"You can override parameters for nested objects:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},'trainer = instantiate(\n cfg.trainer,\n optimizer={"lr": 0.3},\n dataset={"name": "cifar10", "path": "/datasets/cifar10"},\n)\nprint(trainer)\n# Trainer(\n# optimizer=Optimizer(algo=SGD,lr=0.3),\n# dataset=Dataset(name=cifar10, path=/datasets/cifar10)\n# )\n')),(0,r.mdx)("p",null,"Similarly, positional arguments of nested objects can be overridden:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},'obj = instantiate(\n cfg.object,\n # pass 1 and 2 as positional arguments to the target object\n 1, 2, \n # pass 3 and 4 as positional arguments to a nested child object\n child={"_args_": [3, 4]},\n)\n')),(0,r.mdx)("h3",{id:"disable-recursive-instantiation"},"Disable recursive instantiation"),(0,r.mdx)("p",null,"You can disable recursive instantiation by setting ",(0,r.mdx)("inlineCode",{parentName:"p"},"_recursive_")," to ",(0,r.mdx)("inlineCode",{parentName:"p"},"False")," in the config node or in the call-site\nIn that case the Trainer object will receive an OmegaConf DictConfig for nested dataset and optimizer instead of the instantiated objects."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},"optimizer = instantiate(cfg.trainer, _recursive_=False)\nprint(optimizer)\n")),(0,r.mdx)("p",null,"Output:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},"Trainer(\n optimizer={\n '_target_': 'my_app.Optimizer', 'algo': 'SGD', 'lr': 0.01\n },\n dataset={\n '_target_': 'my_app.Dataset', 'name': 'Imagenet', 'path': '/datasets/imagenet'\n }\n)\n")),(0,r.mdx)("h2",{id:"parameter-conversion-strategies"},"Parameter conversion strategies"),(0,r.mdx)("p",null,"By default, the parameters passed to the target are either primitives (int,\nfloat, bool etc) or OmegaConf containers (",(0,r.mdx)("inlineCode",{parentName:"p"},"DictConfig"),", ",(0,r.mdx)("inlineCode",{parentName:"p"},"ListConfig"),").\nOmegaConf containers have many advantages over primitive dicts and lists,\nincluding convenient attribute access for keys,\n",(0,r.mdx)("a",{parentName:"p",href:"https://omegaconf.readthedocs.io/en/latest/structured_config.html"},"duck-typing as instances of dataclasses or attrs classes"),", and\nsupport for ",(0,r.mdx)("a",{parentName:"p",href:"https://omegaconf.readthedocs.io/en/latest/usage.html#variable-interpolation"},"variable interpolation"),"\nand ",(0,r.mdx)("a",{parentName:"p",href:"https://omegaconf.readthedocs.io/en/latest/custom_resolvers.html"},"custom resolvers"),".\nIf the callable targeted by ",(0,r.mdx)("inlineCode",{parentName:"p"},"instantiate")," leverages OmegaConf's features, it\nwill make sense to pass ",(0,r.mdx)("inlineCode",{parentName:"p"},"DictConfig")," and ",(0,r.mdx)("inlineCode",{parentName:"p"},"ListConfig")," instances directly to\nthat callable."),(0,r.mdx)("p",null,"That being said, in many cases it's desired to pass normal Python dicts and\nlists, rather than ",(0,r.mdx)("inlineCode",{parentName:"p"},"DictConfig")," or ",(0,r.mdx)("inlineCode",{parentName:"p"},"ListConfig")," instances, as arguments to your\ncallable. You can change instantiate's argument conversion strategy using the\n",(0,r.mdx)("inlineCode",{parentName:"p"},"_convert_")," parameter. Supported values are:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},'"none"')," : Default behavior, Use OmegaConf containers"),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},'"partial"')," : Convert OmegaConf containers to dict and list, except Structured Configs."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},'"all"')," : Convert everything to primitive containers")),(0,r.mdx)("p",null,"The conversion strategy applies recursively to all subconfigs of the instantiation target.\nHere is an example demonstrating the various conversion strategies:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},'from dataclasses import dataclass\nfrom omegaconf import DictConfig, OmegaConf\nfrom hydra.utils import instantiate\n\n@dataclass\nclass Foo:\n a: int = 123\n\nclass MyTarget:\n def __init__(self, foo, bar):\n self.foo = foo\n self.bar = bar\n\ncfg = OmegaConf.create(\n {\n "_target_": "__main__.MyTarget",\n "foo": Foo(),\n "bar": {"b": 456},\n }\n)\n\nobj_none = instantiate(cfg, _convert_="none")\nassert isinstance(obj_none, MyTarget)\nassert isinstance(obj_none.foo, DictConfig)\nassert isinstance(obj_none.bar, DictConfig)\n\nobj_partial = instantiate(cfg, _convert_="partial")\nassert isinstance(obj_partial, MyTarget)\nassert isinstance(obj_partial.foo, DictConfig)\nassert isinstance(obj_partial.bar, dict)\n\nobj_all = instantiate(cfg, _convert_="all")\nassert isinstance(obj_none, MyTarget)\nassert isinstance(obj_all.foo, dict)\nassert isinstance(obj_all.bar, dict)\n')),(0,r.mdx)("p",null,"Passing the ",(0,r.mdx)("inlineCode",{parentName:"p"},"_convert_")," keyword argument to ",(0,r.mdx)("inlineCode",{parentName:"p"},"instantiate")," has the same effect as defining\na ",(0,r.mdx)("inlineCode",{parentName:"p"},"_convert_")," attribute on your config object. Here is an example creating\ninstances of ",(0,r.mdx)("inlineCode",{parentName:"p"},"MyTarget")," that are equivalent to the above:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},'cfg_none = OmegaConf.create({..., "_convert_": "none"})\nobj_none = instantiate(cfg_none)\n\ncfg_partial = OmegaConf.create({..., "_convert_": "partial"})\nobj_partial = instantiate(cfg_partial)\n\ncfg_all = OmegaConf.create({..., "_convert_": "all"})\nobj_all = instantiate(cfg_all)\n')),(0,r.mdx)("h3",{id:"partial-instantiation-for-hydra-version--112"},"Partial Instantiation (for Hydra version >= 1.1.2)"),(0,r.mdx)("p",null,"Sometimes you may not set all parameters needed to instantiate an object from the configuration, in this case you can set\n",(0,r.mdx)("inlineCode",{parentName:"p"},"_partial_")," to be ",(0,r.mdx)("inlineCode",{parentName:"p"},"True")," to get a ",(0,r.mdx)("inlineCode",{parentName:"p"},"functools.partial")," wrapped object or method, then complete initializing the object in\nthe application code. Here is an example:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Example classes"',title:'"Example','classes"':!0},'class Optimizer:\n algo: str\n lr: float\n\n def __init__(self, algo: str, lr: float) -> None:\n self.algo = algo\n self.lr = lr\n\n def __repr__(self) -> str:\n return f"Optimizer(algo={self.algo},lr={self.lr})"\n\n\nclass Model:\n def __init__(self, optim_partial: Any, lr: float):\n super().__init__()\n self.optim = optim_partial(lr=lr)\n self.lr = lr\n\n def __repr__(self) -> str:\n return f"Model(Optimizer={self.optim},lr={self.lr})"\n')),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--5"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Config"',title:'"Config"'},"model:\n _target_: my_app.Model\n optim_partial:\n _partial_: true\n _target_: my_app.Optimizer\n algo: SGD\n lr: 0.01\n"))),(0,r.mdx)("div",{className:"col col--7"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Instantiation"',title:'"Instantiation"'},'model = instantiate(cfg.model)\nprint(model)\n# "Model(Optimizer=Optimizer(algo=SGD,lr=0.01),lr=0.01)\n')))),(0,r.mdx)("p",null,"If you are repeatedly instantiating the same config,\nusing ",(0,r.mdx)("inlineCode",{parentName:"p"},"_partial_=True")," may provide a significant speedup as compared with regular (non-partial) instantiation."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},"factory = instantiate(config, _partial_=True)\nobj = factory()\n")),(0,r.mdx)("p",null,"In the above example, repeatedly calling ",(0,r.mdx)("inlineCode",{parentName:"p"},"factory")," would be faster than repeatedly calling ",(0,r.mdx)("inlineCode",{parentName:"p"},"instantiate(config)"),".\nA caveat of this approach is that the same keyword arguments would be re-used in each call to ",(0,r.mdx)("inlineCode",{parentName:"p"},"factory"),"."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},'class Foo:\n ...\n\nclass Bar:\n def __init__(self, foo):\n self.foo = foo\n\nbar_conf = {\n "_target_": "__main__.Bar",\n "foo": {"_target_": "__main__.Foo"},\n}\n\nbar_factory = instantiate(bar_conf, _partial_=True)\nbar1 = bar_factory()\nbar2 = bar_factory()\n\nassert bar1 is not bar2\nassert bar1.foo is bar2.foo # the `Foo` instance is re-used here\n')),(0,r.mdx)("p",null,"This does not apply if ",(0,r.mdx)("inlineCode",{parentName:"p"},"_partial_=False"),",\nin which case a new ",(0,r.mdx)("inlineCode",{parentName:"p"},"Foo")," instance would be created with each call to ",(0,r.mdx)("inlineCode",{parentName:"p"},"instantiate"),"."),(0,r.mdx)("h3",{id:"instantiation-of-builtins"},"Instantiation of builtins"),(0,r.mdx)("p",null,"The value of ",(0,r.mdx)("inlineCode",{parentName:"p"},"_target_")," passed to ",(0,r.mdx)("inlineCode",{parentName:"p"},"instantiate"),' should be a "dotpath" pointing\nto some callable that can be looked up via a combination of ',(0,r.mdx)("inlineCode",{parentName:"p"},"import")," and ",(0,r.mdx)("inlineCode",{parentName:"p"},"getattr"),".\nIf you want to target one of Python's ",(0,r.mdx)("a",{parentName:"p",href:"https://docs.python.org/3/library/functions.html"},"built-in functions")," (such as ",(0,r.mdx)("inlineCode",{parentName:"p"},"len")," or ",(0,r.mdx)("inlineCode",{parentName:"p"},"print")," or ",(0,r.mdx)("inlineCode",{parentName:"p"},"divmod"),"),\nyou will need to provide a dotpath looking up that function in Python's ",(0,r.mdx)("a",{parentName:"p",href:"https://docs.python.org/3/library/builtins.html"},(0,r.mdx)("inlineCode",{parentName:"a"},"builtins"))," module."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},'from hydra.utils import instantiate\n# instantiate({"_target_": "len"}, [1,2,3]) # this gives an InstantiationException\ninstantiate({"_target_": "builtins.len"}, [1,2,3]) # this works, returns the number 3\n')))}g.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/06056e6c.94923aa4.js b/assets/js/06056e6c.94923aa4.js deleted file mode 100644 index 14c16d4e92..0000000000 --- a/assets/js/06056e6c.94923aa4.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3350],{15680:(e,t,r)=>{r.r(t),r.d(t,{MDXContext:()=>s,MDXProvider:()=>d,mdx:()=>y,useMDXComponents:()=>u,withMDXComponents:()=>p});var n=r(96540);function o(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(o[r]=e[r]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(o[r]=e[r])}return o}var s=n.createContext({}),p=function(e){return function(t){var r=u(t.components);return n.createElement(e,a({},t,{components:r}))}},u=function(e){var t=n.useContext(s),r=t;return e&&(r="function"==typeof e?e(t):c(c({},t),e)),r},d=function(e){var t=u(e.components);return n.createElement(s.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},f=n.forwardRef((function(e,t){var r=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,s=l(e,["components","mdxType","originalType","parentName"]),p=u(r),d=o,f=p["".concat(i,".").concat(d)]||p[d]||m[d]||a;return r?n.createElement(f,c(c({ref:t},s),{},{components:r})):n.createElement(f,c({ref:t},s))}));function y(e,t){var r=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=r.length,i=new Array(a);i[0]=f;var c={};for(var l in t)hasOwnProperty.call(t,l)&&(c[l]=t[l]);c.originalType=e,c.mdxType="string"==typeof e?e:o,i[1]=c;for(var s=2;s{r.r(t),r.d(t,{contentTitle:()=>l,default:()=>d,frontMatter:()=>c,metadata:()=>s,toc:()=>p});var n=r(58168),o=r(98587),a=(r(96540),r(15680)),i=["components"],c={id:"intro",title:"Introduction",sidebar_label:"Introduction"},l=void 0,s={unversionedId:"experimental/intro",id:"version-1.3/experimental/intro",title:"Introduction",description:"Experimental features are new features in Hydra that are considered experimental because their API may have not yet",source:"@site/versioned_docs/version-1.3/experimental/intro.md",sourceDirName:"experimental",slug:"/experimental/intro",permalink:"/docs/1.3/experimental/intro",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/experimental/intro.md",tags:[],version:"1.3",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"intro",title:"Introduction",sidebar_label:"Introduction"},sidebar:"docs",previous:{title:"Hydra in Unit Tests",permalink:"/docs/1.3/advanced/unit_testing"},next:{title:"Callbacks",permalink:"/docs/1.3/experimental/callbacks"}},p=[],u={toc:p};function d(e){var t=e.components,r=(0,o.A)(e,i);return(0,a.mdx)("wrapper",(0,n.A)({},u,r,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)("p",null,"Experimental features are new features in Hydra that are considered experimental because their API may have not yet\nstabilized."),(0,a.mdx)("p",null,"Those features should all work, but code relying on them may break in future versions as they evolve.\nExperimental features are expected be promoted out of experimental once they deemed stable and complete enough."))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/06056e6c.e4c16df6.js b/assets/js/06056e6c.e4c16df6.js new file mode 100644 index 0000000000..67dd11e437 --- /dev/null +++ b/assets/js/06056e6c.e4c16df6.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3350],{15680:(e,t,r)=>{r.r(t),r.d(t,{MDXContext:()=>s,MDXProvider:()=>d,mdx:()=>y,useMDXComponents:()=>u,withMDXComponents:()=>p});var n=r(96540);function o(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(o[r]=e[r]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(o[r]=e[r])}return o}var s=n.createContext({}),p=function(e){return function(t){var r=u(t.components);return n.createElement(e,a({},t,{components:r}))}},u=function(e){var t=n.useContext(s),r=t;return e&&(r="function"==typeof e?e(t):c(c({},t),e)),r},d=function(e){var t=u(e.components);return n.createElement(s.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},f=n.forwardRef((function(e,t){var r=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,s=l(e,["components","mdxType","originalType","parentName"]),p=u(r),d=o,f=p["".concat(i,".").concat(d)]||p[d]||m[d]||a;return r?n.createElement(f,c(c({ref:t},s),{},{components:r})):n.createElement(f,c({ref:t},s))}));function y(e,t){var r=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=r.length,i=new Array(a);i[0]=f;var c={};for(var l in t)hasOwnProperty.call(t,l)&&(c[l]=t[l]);c.originalType=e,c.mdxType="string"==typeof e?e:o,i[1]=c;for(var s=2;s{r.r(t),r.d(t,{contentTitle:()=>l,default:()=>d,frontMatter:()=>c,metadata:()=>s,toc:()=>p});var n=r(58168),o=r(98587),a=(r(96540),r(15680)),i=["components"],c={id:"intro",title:"Introduction",sidebar_label:"Introduction"},l=void 0,s={unversionedId:"experimental/intro",id:"version-1.3/experimental/intro",title:"Introduction",description:"Experimental features are new features in Hydra that are considered experimental because their API may have not yet",source:"@site/versioned_docs/version-1.3/experimental/intro.md",sourceDirName:"experimental",slug:"/experimental/intro",permalink:"/docs/1.3/experimental/intro",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/experimental/intro.md",tags:[],version:"1.3",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"intro",title:"Introduction",sidebar_label:"Introduction"},sidebar:"docs",previous:{title:"Hydra in Unit Tests",permalink:"/docs/1.3/advanced/unit_testing"},next:{title:"Callbacks",permalink:"/docs/1.3/experimental/callbacks"}},p=[],u={toc:p};function d(e){var t=e.components,r=(0,o.A)(e,i);return(0,a.mdx)("wrapper",(0,n.A)({},u,r,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)("p",null,"Experimental features are new features in Hydra that are considered experimental because their API may have not yet\nstabilized."),(0,a.mdx)("p",null,"Those features should all work, but code relying on them may break in future versions as they evolve.\nExperimental features are expected be promoted out of experimental once they deemed stable and complete enough."))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/0689266f.553bee8e.js b/assets/js/0689266f.553bee8e.js deleted file mode 100644 index a9c38c93b9..0000000000 --- a/assets/js/0689266f.553bee8e.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[2004],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>c,MDXProvider:()=>u,mdx:()=>h,useMDXComponents:()=>d,withMDXComponents:()=>p});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(){return i=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var c=r.createContext({}),p=function(e){return function(t){var n=d(t.components);return r.createElement(e,i({},t,{components:n}))}},d=function(e){var t=r.useContext(c),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},u=function(e){var t=d(e.components);return r.createElement(c.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},f=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,i=e.originalType,a=e.parentName,c=s(e,["components","mdxType","originalType","parentName"]),p=d(n),u=o,f=p["".concat(a,".").concat(u)]||p[u]||m[u]||i;return n?r.createElement(f,l(l({ref:t},c),{},{components:n})):r.createElement(f,l({ref:t},c))}));function h(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var i=n.length,a=new Array(i);a[0]=f;var l={};for(var s in t)hasOwnProperty.call(t,s)&&(l[s]=t[s]);l.originalType=e,l.mdxType="string"==typeof e?e:o,a[1]=l;for(var c=2;c{n.d(t,{A:()=>o});var r=n(96540);function o(e){var t=(0,r.useRef)(null),n=(0,r.useRef)("undefined"!=typeof document?document.createElement("script"):null);return(0,r.useEffect)((function(){t.current.appendChild(n.current)}),[]),(0,r.useEffect)((function(){for(var t in e)e.hasOwnProperty(t)&&(n.current[t]=e[t])})),r.createElement("div",{ref:t})}},25521:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>c,default:()=>m,frontMatter:()=>s,metadata:()=>p,toc:()=>d});var r=n(58168),o=n(98587),i=(n(96540),n(15680)),a=n(57259),l=["components"],s={id:"tab_completion",title:"Tab completion",sidebar_label:"Tab completion"},c=void 0,p={unversionedId:"tutorials/basic/running_your_app/tab_completion",id:"version-1.2/tutorials/basic/running_your_app/tab_completion",title:"Tab completion",description:"Tab completion can complete config groups, config nodes and values.",source:"@site/versioned_docs/version-1.2/tutorials/basic/running_your_app/6_tab_completion.md",sourceDirName:"tutorials/basic/running_your_app",slug:"/tutorials/basic/running_your_app/tab_completion",permalink:"/docs/1.2/tutorials/basic/running_your_app/tab_completion",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/tutorials/basic/running_your_app/6_tab_completion.md",tags:[],version:"1.2",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:6,frontMatter:{id:"tab_completion",title:"Tab completion",sidebar_label:"Tab completion"},sidebar:"docs",previous:{title:"Debugging",permalink:"/docs/1.2/tutorials/basic/running_your_app/debugging"},next:{title:"Introduction to Structured Configs",permalink:"/docs/1.2/tutorials/structured_config/intro"}},d=[{value:"Install tab completion",id:"install-tab-completion",children:[{value:"Fish instructions",id:"fish-instructions",children:[],level:4},{value:"Zsh instructions",id:"zsh-instructions",children:[],level:4}],level:3}],u={toc:d};function m(e){var t=e.components,n=(0,o.A)(e,l);return(0,i.mdx)("wrapper",(0,r.A)({},u,n,{components:t,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Tab completion can complete config groups, config nodes and values.\nTo complete paths, start them with ",(0,i.mdx)("inlineCode",{parentName:"p"},"/")," or ",(0,i.mdx)("inlineCode",{parentName:"p"},"./"),"."),(0,i.mdx)("p",null,"See this short video demonstration of tab completion:"),(0,i.mdx)(a.A,{id:"asciicast-272604",src:"https://asciinema.org/a/272604.js",async:!0,mdxType:"Script"}),(0,i.mdx)("h3",{id:"install-tab-completion"},"Install tab completion"),(0,i.mdx)("p",null,"Get the exact command to install the completion from ",(0,i.mdx)("inlineCode",{parentName:"p"},"--hydra-help"),".\nCurrently, Bash, zsh and Fish are supported.\nWe are relying on the community to implement tab completion plugins for additional shells."),(0,i.mdx)("h4",{id:"fish-instructions"},"Fish instructions"),(0,i.mdx)("p",null,"Fish support requires version >= 3.1.2.\nPrevious versions will work but add an extra space after ",(0,i.mdx)("inlineCode",{parentName:"p"},"."),"."),(0,i.mdx)("p",null,"Because the fish shell implements special behavior for expanding words prefixed\nwith a tilde character '~', command-line completion does not work for\n",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.2/advanced/override_grammar/basic#modifying-the-defaults-list"},"tilde deletions"),"."),(0,i.mdx)("h4",{id:"zsh-instructions"},"Zsh instructions"),(0,i.mdx)("p",null,"Zsh is compatible with the existing Bash shell completion by appending"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre"},"autoload -Uz bashcompinit && bashcompinit\n")),(0,i.mdx)("p",null,"to the ",(0,i.mdx)("inlineCode",{parentName:"p"},".zshrc")," file after ",(0,i.mdx)("inlineCode",{parentName:"p"},"compinit"),", restarting the shell and then using the commands provided for Bash."),(0,i.mdx)("p",null,"Because the zsh shell implements special behavior for expanding words prefixed\nwith a tilde character '~', command-line completion does not work for\n",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.2/advanced/override_grammar/basic#modifying-the-defaults-list"},"tilde deletions"),"."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/0689266f.acc40ed9.js b/assets/js/0689266f.acc40ed9.js new file mode 100644 index 0000000000..b1a3b4b194 --- /dev/null +++ b/assets/js/0689266f.acc40ed9.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[2004],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>c,MDXProvider:()=>u,mdx:()=>h,useMDXComponents:()=>d,withMDXComponents:()=>p});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(){return i=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var c=r.createContext({}),p=function(e){return function(t){var n=d(t.components);return r.createElement(e,i({},t,{components:n}))}},d=function(e){var t=r.useContext(c),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},u=function(e){var t=d(e.components);return r.createElement(c.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},f=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,i=e.originalType,a=e.parentName,c=s(e,["components","mdxType","originalType","parentName"]),p=d(n),u=o,f=p["".concat(a,".").concat(u)]||p[u]||m[u]||i;return n?r.createElement(f,l(l({ref:t},c),{},{components:n})):r.createElement(f,l({ref:t},c))}));function h(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var i=n.length,a=new Array(i);a[0]=f;var l={};for(var s in t)hasOwnProperty.call(t,s)&&(l[s]=t[s]);l.originalType=e,l.mdxType="string"==typeof e?e:o,a[1]=l;for(var c=2;c{n.d(t,{A:()=>o});var r=n(96540);function o(e){var t=(0,r.useRef)(null),n=(0,r.useRef)("undefined"!=typeof document?document.createElement("script"):null);return(0,r.useEffect)((function(){t.current.appendChild(n.current)}),[]),(0,r.useEffect)((function(){for(var t in e)e.hasOwnProperty(t)&&(n.current[t]=e[t])})),r.createElement("div",{ref:t})}},25521:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>c,default:()=>m,frontMatter:()=>s,metadata:()=>p,toc:()=>d});var r=n(58168),o=n(98587),i=(n(96540),n(15680)),a=n(57259),l=["components"],s={id:"tab_completion",title:"Tab completion",sidebar_label:"Tab completion"},c=void 0,p={unversionedId:"tutorials/basic/running_your_app/tab_completion",id:"version-1.2/tutorials/basic/running_your_app/tab_completion",title:"Tab completion",description:"Tab completion can complete config groups, config nodes and values.",source:"@site/versioned_docs/version-1.2/tutorials/basic/running_your_app/6_tab_completion.md",sourceDirName:"tutorials/basic/running_your_app",slug:"/tutorials/basic/running_your_app/tab_completion",permalink:"/docs/1.2/tutorials/basic/running_your_app/tab_completion",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/tutorials/basic/running_your_app/6_tab_completion.md",tags:[],version:"1.2",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:6,frontMatter:{id:"tab_completion",title:"Tab completion",sidebar_label:"Tab completion"},sidebar:"docs",previous:{title:"Debugging",permalink:"/docs/1.2/tutorials/basic/running_your_app/debugging"},next:{title:"Introduction to Structured Configs",permalink:"/docs/1.2/tutorials/structured_config/intro"}},d=[{value:"Install tab completion",id:"install-tab-completion",children:[{value:"Fish instructions",id:"fish-instructions",children:[],level:4},{value:"Zsh instructions",id:"zsh-instructions",children:[],level:4}],level:3}],u={toc:d};function m(e){var t=e.components,n=(0,o.A)(e,l);return(0,i.mdx)("wrapper",(0,r.A)({},u,n,{components:t,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Tab completion can complete config groups, config nodes and values.\nTo complete paths, start them with ",(0,i.mdx)("inlineCode",{parentName:"p"},"/")," or ",(0,i.mdx)("inlineCode",{parentName:"p"},"./"),"."),(0,i.mdx)("p",null,"See this short video demonstration of tab completion:"),(0,i.mdx)(a.A,{id:"asciicast-272604",src:"https://asciinema.org/a/272604.js",async:!0,mdxType:"Script"}),(0,i.mdx)("h3",{id:"install-tab-completion"},"Install tab completion"),(0,i.mdx)("p",null,"Get the exact command to install the completion from ",(0,i.mdx)("inlineCode",{parentName:"p"},"--hydra-help"),".\nCurrently, Bash, zsh and Fish are supported.\nWe are relying on the community to implement tab completion plugins for additional shells."),(0,i.mdx)("h4",{id:"fish-instructions"},"Fish instructions"),(0,i.mdx)("p",null,"Fish support requires version >= 3.1.2.\nPrevious versions will work but add an extra space after ",(0,i.mdx)("inlineCode",{parentName:"p"},"."),"."),(0,i.mdx)("p",null,"Because the fish shell implements special behavior for expanding words prefixed\nwith a tilde character '~', command-line completion does not work for\n",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.2/advanced/override_grammar/basic#modifying-the-defaults-list"},"tilde deletions"),"."),(0,i.mdx)("h4",{id:"zsh-instructions"},"Zsh instructions"),(0,i.mdx)("p",null,"Zsh is compatible with the existing Bash shell completion by appending"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre"},"autoload -Uz bashcompinit && bashcompinit\n")),(0,i.mdx)("p",null,"to the ",(0,i.mdx)("inlineCode",{parentName:"p"},".zshrc")," file after ",(0,i.mdx)("inlineCode",{parentName:"p"},"compinit"),", restarting the shell and then using the commands provided for Bash."),(0,i.mdx)("p",null,"Because the zsh shell implements special behavior for expanding words prefixed\nwith a tilde character '~', command-line completion does not work for\n",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.2/advanced/override_grammar/basic#modifying-the-defaults-list"},"tilde deletions"),"."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/06963ee3.08164d91.js b/assets/js/06963ee3.08164d91.js deleted file mode 100644 index 1bb48b988a..0000000000 --- a/assets/js/06963ee3.08164d91.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[7264],{15680:(e,r,t)=>{t.r(r),t.d(r,{MDXContext:()=>l,MDXProvider:()=>u,mdx:()=>v,useMDXComponents:()=>m,withMDXComponents:()=>p});var n=t(96540);function a(e,r,t){return r in e?Object.defineProperty(e,r,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[r]=t,e}function o(){return o=Object.assign||function(e){for(var r=1;r=0||(a[t]=e[t]);return a}(e,r);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(a[t]=e[t])}return a}var l=n.createContext({}),p=function(e){return function(r){var t=m(r.components);return n.createElement(e,o({},r,{components:t}))}},m=function(e){var r=n.useContext(l),t=r;return e&&(t="function"==typeof e?e(r):s(s({},r),e)),t},u=function(e){var r=m(e.components);return n.createElement(l.Provider,{value:r},e.children)},c={inlineCode:"code",wrapper:function(e){var r=e.children;return n.createElement(n.Fragment,{},r)}},g=n.forwardRef((function(e,r){var t=e.components,a=e.mdxType,o=e.originalType,i=e.parentName,l=d(e,["components","mdxType","originalType","parentName"]),p=m(t),u=a,g=p["".concat(i,".").concat(u)]||p[u]||c[u]||o;return t?n.createElement(g,s(s({ref:r},l),{},{components:t})):n.createElement(g,s({ref:r},l))}));function v(e,r){var t=arguments,a=r&&r.mdxType;if("string"==typeof e||a){var o=t.length,i=new Array(o);i[0]=g;var s={};for(var d in r)hasOwnProperty.call(r,d)&&(s[d]=r[d]);s.originalType=e,s.mdxType="string"==typeof e?e:a,i[1]=s;for(var l=2;l{t.r(r),t.d(r,{contentTitle:()=>d,default:()=>u,frontMatter:()=>s,metadata:()=>l,toc:()=>p});var n=t(58168),a=t(98587),o=(t(96540),t(15680)),i=["components"],s={id:"intro",title:"Introduction",sidebar_label:"Introduction"},d=void 0,l={unversionedId:"upgrades/intro",id:"version-1.3/upgrades/intro",title:"Introduction",description:"Upgrading to a new Hydra version is usually an easy process.",source:"@site/versioned_docs/version-1.3/upgrades/intro.md",sourceDirName:"upgrades",slug:"/upgrades/intro",permalink:"/docs/1.3/upgrades/intro",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/upgrades/intro.md",tags:[],version:"1.3",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"intro",title:"Introduction",sidebar_label:"Introduction"},sidebar:"docs",previous:{title:"Release process",permalink:"/docs/1.3/development/release"},next:{title:"version_base",permalink:"/docs/1.3/upgrades/version_base"}},p=[{value:"Major version upgrades",id:"major-version-upgrades",children:[],level:2},{value:"Patch version upgrades",id:"patch-version-upgrades",children:[],level:2},{value:"Dev release upgrades",id:"dev-release-upgrades",children:[],level:2}],m={toc:p};function u(e){var r=e.components,t=(0,a.A)(e,i);return(0,o.mdx)("wrapper",(0,n.A)({},m,t,{components:r,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"Upgrading to a new Hydra version is usually an easy process.\nAlso since Hydra version 1.2, backwards compatibility is improved\nby giving the user more control over appropriate defaults\nthrough the use of the ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.3/upgrades/version_base"},"version_base parameter"),"."),(0,o.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,o.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,o.mdx)("h5",{parentName:"div"},(0,o.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,o.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,o.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"NOTE")),(0,o.mdx)("div",{parentName:"div",className:"admonition-content"},(0,o.mdx)("p",{parentName:"div"},"Hydra versioning has only major versions and patch versions. A bump of the first two version digits is considered a major release.\nA major release may have multiple followup patch releases that will fix bugs without introducing new functionality."))),(0,o.mdx)("h2",{id:"major-version-upgrades"},"Major version upgrades"),(0,o.mdx)("p",null,"Hydra will typically provide helpful warnings about required changes, sometimes pointing to an upgrade page that provides more details about the required changes."),(0,o.mdx)("p",null,"For a smooth upgrade experience, please follow these simple rules:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("strong",{parentName:"li"},"Upgrade to the latest patch version first"),".\ne.g: If you are upgrading from 1.0 to 1.1, be sure to upgrade to the latest 1.0 version first (1.0.6)."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("strong",{parentName:"li"},"Address ALL runtime warnings issued by Hydra."),(0,o.mdx)("br",{parentName:"li"}),"A warning in one version is likely to become a far less friendly error in the next major version."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("strong",{parentName:"li"},"Do not skip major versions"),".",(0,o.mdx)("br",{parentName:"li"}),"e.g: If you are upgrading from Hydra 1.0 to Hydra 1.2 - Do it by",(0,o.mdx)("ul",{parentName:"li"},(0,o.mdx)("li",{parentName:"ul"},"Upgrading from 1.0 to 1.1, addressing all the warnings."),(0,o.mdx)("li",{parentName:"ul"},"Upgrading from 1.1 to 1.2, addressing all the warnings.")))),(0,o.mdx)("h2",{id:"patch-version-upgrades"},"Patch version upgrades"),(0,o.mdx)("p",null,"Patch releases normally contains only bug fixes and are thus safe and easy to upgrade (e.g. ",(0,o.mdx)("strong",{parentName:"p"},"1.0.3")," to ",(0,o.mdx)("strong",{parentName:"p"},"1.0.6"),").",(0,o.mdx)("br",{parentName:"p"}),"\n","In rare cases, patch releases will introduce new warnings. Be sure to address them before upgrading to the next major version."),(0,o.mdx)("h2",{id:"dev-release-upgrades"},"Dev release upgrades"),(0,o.mdx)("p",null,"Development releases are subject to breaking changes without notice. Please be aware that upgrading to a new development release\nis more likely to introduce some breakage. No attempt will be made to make upgrading between development releases easy."))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/06963ee3.f545a00c.js b/assets/js/06963ee3.f545a00c.js new file mode 100644 index 0000000000..d80865d627 --- /dev/null +++ b/assets/js/06963ee3.f545a00c.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[7264],{15680:(e,r,t)=>{t.r(r),t.d(r,{MDXContext:()=>l,MDXProvider:()=>u,mdx:()=>v,useMDXComponents:()=>m,withMDXComponents:()=>p});var n=t(96540);function a(e,r,t){return r in e?Object.defineProperty(e,r,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[r]=t,e}function o(){return o=Object.assign||function(e){for(var r=1;r=0||(a[t]=e[t]);return a}(e,r);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(a[t]=e[t])}return a}var l=n.createContext({}),p=function(e){return function(r){var t=m(r.components);return n.createElement(e,o({},r,{components:t}))}},m=function(e){var r=n.useContext(l),t=r;return e&&(t="function"==typeof e?e(r):s(s({},r),e)),t},u=function(e){var r=m(e.components);return n.createElement(l.Provider,{value:r},e.children)},c={inlineCode:"code",wrapper:function(e){var r=e.children;return n.createElement(n.Fragment,{},r)}},g=n.forwardRef((function(e,r){var t=e.components,a=e.mdxType,o=e.originalType,i=e.parentName,l=d(e,["components","mdxType","originalType","parentName"]),p=m(t),u=a,g=p["".concat(i,".").concat(u)]||p[u]||c[u]||o;return t?n.createElement(g,s(s({ref:r},l),{},{components:t})):n.createElement(g,s({ref:r},l))}));function v(e,r){var t=arguments,a=r&&r.mdxType;if("string"==typeof e||a){var o=t.length,i=new Array(o);i[0]=g;var s={};for(var d in r)hasOwnProperty.call(r,d)&&(s[d]=r[d]);s.originalType=e,s.mdxType="string"==typeof e?e:a,i[1]=s;for(var l=2;l{t.r(r),t.d(r,{contentTitle:()=>d,default:()=>u,frontMatter:()=>s,metadata:()=>l,toc:()=>p});var n=t(58168),a=t(98587),o=(t(96540),t(15680)),i=["components"],s={id:"intro",title:"Introduction",sidebar_label:"Introduction"},d=void 0,l={unversionedId:"upgrades/intro",id:"version-1.3/upgrades/intro",title:"Introduction",description:"Upgrading to a new Hydra version is usually an easy process.",source:"@site/versioned_docs/version-1.3/upgrades/intro.md",sourceDirName:"upgrades",slug:"/upgrades/intro",permalink:"/docs/1.3/upgrades/intro",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/upgrades/intro.md",tags:[],version:"1.3",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"intro",title:"Introduction",sidebar_label:"Introduction"},sidebar:"docs",previous:{title:"Release process",permalink:"/docs/1.3/development/release"},next:{title:"version_base",permalink:"/docs/1.3/upgrades/version_base"}},p=[{value:"Major version upgrades",id:"major-version-upgrades",children:[],level:2},{value:"Patch version upgrades",id:"patch-version-upgrades",children:[],level:2},{value:"Dev release upgrades",id:"dev-release-upgrades",children:[],level:2}],m={toc:p};function u(e){var r=e.components,t=(0,a.A)(e,i);return(0,o.mdx)("wrapper",(0,n.A)({},m,t,{components:r,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"Upgrading to a new Hydra version is usually an easy process.\nAlso since Hydra version 1.2, backwards compatibility is improved\nby giving the user more control over appropriate defaults\nthrough the use of the ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.3/upgrades/version_base"},"version_base parameter"),"."),(0,o.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,o.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,o.mdx)("h5",{parentName:"div"},(0,o.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,o.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,o.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"NOTE")),(0,o.mdx)("div",{parentName:"div",className:"admonition-content"},(0,o.mdx)("p",{parentName:"div"},"Hydra versioning has only major versions and patch versions. A bump of the first two version digits is considered a major release.\nA major release may have multiple followup patch releases that will fix bugs without introducing new functionality."))),(0,o.mdx)("h2",{id:"major-version-upgrades"},"Major version upgrades"),(0,o.mdx)("p",null,"Hydra will typically provide helpful warnings about required changes, sometimes pointing to an upgrade page that provides more details about the required changes."),(0,o.mdx)("p",null,"For a smooth upgrade experience, please follow these simple rules:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("strong",{parentName:"li"},"Upgrade to the latest patch version first"),".\ne.g: If you are upgrading from 1.0 to 1.1, be sure to upgrade to the latest 1.0 version first (1.0.6)."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("strong",{parentName:"li"},"Address ALL runtime warnings issued by Hydra."),(0,o.mdx)("br",{parentName:"li"}),"A warning in one version is likely to become a far less friendly error in the next major version."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("strong",{parentName:"li"},"Do not skip major versions"),".",(0,o.mdx)("br",{parentName:"li"}),"e.g: If you are upgrading from Hydra 1.0 to Hydra 1.2 - Do it by",(0,o.mdx)("ul",{parentName:"li"},(0,o.mdx)("li",{parentName:"ul"},"Upgrading from 1.0 to 1.1, addressing all the warnings."),(0,o.mdx)("li",{parentName:"ul"},"Upgrading from 1.1 to 1.2, addressing all the warnings.")))),(0,o.mdx)("h2",{id:"patch-version-upgrades"},"Patch version upgrades"),(0,o.mdx)("p",null,"Patch releases normally contains only bug fixes and are thus safe and easy to upgrade (e.g. ",(0,o.mdx)("strong",{parentName:"p"},"1.0.3")," to ",(0,o.mdx)("strong",{parentName:"p"},"1.0.6"),").",(0,o.mdx)("br",{parentName:"p"}),"\n","In rare cases, patch releases will introduce new warnings. Be sure to address them before upgrading to the next major version."),(0,o.mdx)("h2",{id:"dev-release-upgrades"},"Dev release upgrades"),(0,o.mdx)("p",null,"Development releases are subject to breaking changes without notice. Please be aware that upgrading to a new development release\nis more likely to introduce some breakage. No attempt will be made to make upgrading between development releases easy."))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/07586c7f.6108efa5.js b/assets/js/07586c7f.6108efa5.js new file mode 100644 index 0000000000..e3004af1aa --- /dev/null +++ b/assets/js/07586c7f.6108efa5.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[9021],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>m,MDXProvider:()=>c,mdx:()=>g,useMDXComponents:()=>p,withMDXComponents:()=>s});var t=a(96540);function l(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function r(){return r=Object.assign||function(e){for(var n=1;n=0||(l[a]=e[a]);return l}(e,n);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(l[a]=e[a])}return l}var m=t.createContext({}),s=function(e){return function(n){var a=p(n.components);return t.createElement(e,r({},n,{components:a}))}},p=function(e){var n=t.useContext(m),a=n;return e&&(a="function"==typeof e?e(n):d(d({},n),e)),a},c=function(e){var n=p(e.components);return t.createElement(m.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return t.createElement(t.Fragment,{},n)}},f=t.forwardRef((function(e,n){var a=e.components,l=e.mdxType,r=e.originalType,i=e.parentName,m=o(e,["components","mdxType","originalType","parentName"]),s=p(a),c=l,f=s["".concat(i,".").concat(c)]||s[c]||u[c]||r;return a?t.createElement(f,d(d({ref:n},m),{},{components:a})):t.createElement(f,d({ref:n},m))}));function g(e,n){var a=arguments,l=n&&n.mdxType;if("string"==typeof e||l){var r=a.length,i=new Array(r);i[0]=f;var d={};for(var o in n)hasOwnProperty.call(n,o)&&(d[o]=n[o]);d.originalType=e,d.mdxType="string"==typeof e?e:l,i[1]=d;for(var m=2;m{a.r(n),a.d(n,{contentTitle:()=>o,default:()=>c,frontMatter:()=>d,metadata:()=>m,toc:()=>s});var t=a(58168),l=a(98587),r=(a(96540),a(15680)),i=["components"],d={id:"defaults_list",title:"The Defaults List"},o=void 0,m={unversionedId:"advanced/defaults_list",id:"version-1.1/advanced/defaults_list",title:"The Defaults List",description:"Introduction",source:"@site/versioned_docs/version-1.1/advanced/defaults_list.md",sourceDirName:"advanced",slug:"/advanced/defaults_list",permalink:"/docs/1.1/advanced/defaults_list",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/advanced/defaults_list.md",tags:[],version:"1.1",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"defaults_list",title:"The Defaults List"},sidebar:"version-1.1/docs",previous:{title:"Extended Override syntax",permalink:"/docs/1.1/advanced/override_grammar/extended"},next:{title:"Packages",permalink:"/docs/1.1/advanced/overriding_packages"}},s=[{value:"Introduction",id:"introduction",children:[],level:2},{value:"An example",id:"an-example",children:[],level:2},{value:"Overriding Config Group options",id:"overriding-config-group-options",children:[],level:2},{value:"Composition order",id:"composition-order",children:[],level:2},{value:"Interpolation in the Defaults List",id:"interpolation-in-the-defaults-list",children:[{value:"Restrictions:",id:"restrictions",children:[],level:4}],level:2},{value:"Debugging the Defaults List",id:"debugging-the-defaults-list",children:[],level:2},{value:"Related topics",id:"related-topics",children:[],level:2}],p={toc:s};function c(e){var n=e.components,a=(0,l.A)(e,i);return(0,r.mdx)("wrapper",(0,t.A)({},p,a,{components:n,mdxType:"MDXLayout"}),(0,r.mdx)("h2",{id:"introduction"},"Introduction"),(0,r.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,r.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,r.mdx)("h5",{parentName:"div"},(0,r.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,r.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,r.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,r.mdx)("div",{parentName:"div",className:"admonition-content"},(0,r.mdx)("p",{parentName:"div"},"Many of the features described in this page are new. Please report any issues."))),(0,r.mdx)("p",null,"The Defaults List is a list in an input config that instructs Hydra how to build the output config.\nEach input config can have a Defaults List as a top level element. The Defaults List itself\nis not a part of output config."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Defaults List YAML syntax"',title:'"Defaults',List:!0,YAML:!0,'syntax"':!0},"defaults:\n (- CONFIG|GROUP_DEFAULT)*\n\nCONFIG : (CONFIG_GROUP/)?CONFIG_NAME(@PACKAGE)?\nGROUP_DEFAULT : [optional|override]? CONFIG_GROUP(@PACKAGE)?: OPTION\nOPTION : CONFIG_NAME|CONFIG_NAMES|null\n")),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"CONFIG")," : A config to use when creating the output config. e.g. ",(0,r.mdx)("inlineCode",{parentName:"p"},"db/mysql"),", ",(0,r.mdx)("inlineCode",{parentName:"p"},"db/mysql@backup"),"."),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"GROUP_DEFAULT")," : An ",(0,r.mdx)("em",{parentName:"p"},"overridable")," config. e.g. ",(0,r.mdx)("inlineCode",{parentName:"p"},"db: mysql"),", ",(0,r.mdx)("inlineCode",{parentName:"p"},"db@backup: mysql"),"."),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("strong",{parentName:"li"},(0,r.mdx)("em",{parentName:"strong"},"override"))," : Overrides the option of a previously defined GROUP_DEFAULT."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("strong",{parentName:"li"},(0,r.mdx)("em",{parentName:"strong"},"optional"))," : By default, an OPTION that do not exist causes an error; optional suppresses the error. "),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("strong",{parentName:"li"},(0,r.mdx)("em",{parentName:"strong"},"null"))," : A place-holder for a future override. If it is not overridden the entry is ignored.")),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"CONFIG_NAME"),": The name of a config, without the file system extension. e.g. ",(0,r.mdx)("inlineCode",{parentName:"p"},"mysql")," and not ",(0,r.mdx)("inlineCode",{parentName:"p"},"mysql.yaml"),"."),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"CONFIG_NAMES")," : A list of config names. e.g. ",(0,r.mdx)("inlineCode",{parentName:"p"},"[mysql, sqlite]")),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"CONFIG_GROUP")," : A path to a set of configs.",(0,r.mdx)("br",{parentName:"p"}),"\n","The path is relative to the containing config.\nIt can be made absolute by prefixing it with a ",(0,r.mdx)("inlineCode",{parentName:"p"},"/"),".",(0,r.mdx)("br",{parentName:"p"}),"\n","The path separator is ",(0,r.mdx)("inlineCode",{parentName:"p"},"/")," regardless of the operating system."),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"OPTION"),": The currently selected ",(0,r.mdx)("em",{parentName:"p"},"CONFIG_NAME")," or ",(0,r.mdx)("em",{parentName:"p"},"CONFIG_NAMES")," from a ",(0,r.mdx)("em",{parentName:"p"},"CONFIG_GROUP"),". "),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"PACKAGE")," : Where to place the content of the config within the output config.\nIt is relative to the Package of the containing config by default. See ",(0,r.mdx)("a",{parentName:"p",href:"/docs/1.1/advanced/overriding_packages"},"Packages"),"."),(0,r.mdx)("h2",{id:"an-example"},"An example"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Config directory structure"',title:'"Config',directory:!0,'structure"':!0},"\u251c\u2500\u2500 server\n\u2502 \u251c\u2500\u2500 db\n\u2502 \u2502 \u251c\u2500\u2500 mysql.yaml\n\u2502 \u2502 \u2514\u2500\u2500 sqlite.yaml\n\u2502 \u2514\u2500\u2500 apache.yaml\n\u2514\u2500\u2500 config.yaml\n")),(0,r.mdx)("p",null,"Input configs:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - server/apache\n\ndebug: false\n\n\n\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/apache.yaml"',title:'"server/apache.yaml"'},"defaults:\n - db: mysql\n\nname: apache\n\n\n\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/db/mysql.yaml"',title:'"server/db/mysql.yaml"'},"name: mysql\n")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/db/sqlite.yaml"',title:'"server/db/sqlite.yaml"'},"name: sqlite\n")))),(0,r.mdx)("p",null,"Output config:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py"',title:'"$',python:!0,'my_app.py"':!0},"server:\n db:\n name: mysql\n name: apache\ndebug: false\n")),(0,r.mdx)("h2",{id:"overriding-config-group-options"},"Overriding Config Group options"),(0,r.mdx)("p",null,"A Config Group's option can be overridden using a new ",(0,r.mdx)("em",{parentName:"p"},"GROUP_DEFAULT")," with the ",(0,r.mdx)("strong",{parentName:"p"},(0,r.mdx)("em",{parentName:"strong"},"override"))," keyword.\nIf a Group Default is overridden more than once, the last one, in depth first order, wins."),(0,r.mdx)("p",null,"Extending the previous example:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {3}',title:'"config.yaml"',"{3}":!0},"defaults:\n - server/apache\n - override server/db: sqlite\n\ndebug: false\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py" {2,3}',title:'"$',python:!0,'my_app.py"':!0,"{2,3}":!0},"server:\n db:\n name: sqlite\n name: apache\ndebug: false\n")))),(0,r.mdx)("p",null,"A Config Group's option can also be overridden via the command line. e.g: "),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre"},"$ python my_app.py server/db=sqlite\n")),(0,r.mdx)("h2",{id:"composition-order"},"Composition order"),(0,r.mdx)("p",null,"The Defaults List is ordered:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"If multiple configs define the same value, the last one wins."),(0,r.mdx)("li",{parentName:"ul"},"If multiple configs contribute to the same dictionary, the result is the combined dictionary.")),(0,r.mdx)("p",null,"By default, the content of a config is overriding the content of configs in the defaults list."),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {5}',title:'"config.yaml"',"{5}":!0},"defaults:\n - db: mysql \n\ndb:\n host: backup\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Result: db.host from config" {3}',title:'"Result:',"db.host":!0,from:!0,'config"':!0,"{3}":!0},"db:\n driver: mysql # db/mysql.yaml\n host: backup # config.yaml\n port: 3306 # db/mysql.yaml\n\n")))),(0,r.mdx)("p",null,"The ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," entry determines the relative position of ",(0,r.mdx)("strong",{parentName:"p"},"this")," config in the Defaults List.\nIf it is not specified, it is added automatically as the last item."),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {2,6}',title:'"config.yaml"',"{2,6}":!0},"defaults:\n - _self_\n - db: mysql # Overrides this config \n\ndb:\n host: backup\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Result: All values from db/mysql" {3}',title:'"Result:',All:!0,values:!0,from:!0,'db/mysql"':!0,"{3}":!0},"db:\n driver: mysql # db/mysql.yaml\n host: localhost # db/mysql.yaml\n port: 3306 # db/mysql.yaml\n\n\n")))),(0,r.mdx)("p",null,"With ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," at the top of the Defaults List, the host field defined in ",(0,r.mdx)("em",{parentName:"p"},"config.yaml")," now precedes the host field defined\nin ",(0,r.mdx)("em",{parentName:"p"},"db/mysql.yaml"),", and as a result is overridden."),(0,r.mdx)("h2",{id:"interpolation-in-the-defaults-list"},"Interpolation in the Defaults List"),(0,r.mdx)("p",null,"Config Group Options can be selected using interpolation."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - server: apache\n - db: mysql\n - combination_specific_config: ${server}_${db} # apache_mysql\n")),(0,r.mdx)("p",null,"Interpolation keys can be config groups with any @package overrides.",(0,r.mdx)("br",{parentName:"p"}),"\n","For example: ",(0,r.mdx)("inlineCode",{parentName:"p"},"${db/engine}"),", ",(0,r.mdx)("inlineCode",{parentName:"p"},"${db@backup}")),(0,r.mdx)("p",null,"The selected option for ",(0,r.mdx)("em",{parentName:"p"},"combination_specific_config")," depends on the final selected options for ",(0,r.mdx)("em",{parentName:"p"},"db")," and ",(0,r.mdx)("em",{parentName:"p"},"server"),".",(0,r.mdx)("br",{parentName:"p"}),"\n","e.g., If ",(0,r.mdx)("em",{parentName:"p"},"db")," is overridden to ",(0,r.mdx)("em",{parentName:"p"},"sqlite"),", ",(0,r.mdx)("em",{parentName:"p"},"combination_specific_config")," will become ",(0,r.mdx)("em",{parentName:"p"},"apache_sqlite"),"."),(0,r.mdx)("h4",{id:"restrictions"},"Restrictions:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Interpolation keys in the Defaults List cannot reference values in the Final Config Object (it does not yet exist)."),(0,r.mdx)("li",{parentName:"ul"},"Defaults List interpolation keys are absolute (even in nested configs)."),(0,r.mdx)("li",{parentName:"ul"},"The subtree expanded by an Interpolated Config may not contain Default List overrides.")),(0,r.mdx)("p",null,"See ",(0,r.mdx)("a",{parentName:"p",href:"/docs/1.1/patterns/specializing_config"},"Patterns/Specializing Configs")," for more information."),(0,r.mdx)("h2",{id:"debugging-the-defaults-list"},"Debugging the Defaults List"),(0,r.mdx)("p",null,"Hydra's config composition process is as follows:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"The Defaults Tree is created."),(0,r.mdx)("li",{parentName:"ul"},"The Final Defaults List is created via a DFS walk of the Defaults Tree."),(0,r.mdx)("li",{parentName:"ul"},"The Output Config is composed from the entries in the Final Defaults List.")),(0,r.mdx)("p",null,"You can inspect these artifacts via command line flags:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"--info defaults-tree")," shows the Defaults Tree."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"--info defaults")," Shows the Final Defaults List."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"--cfg job|hydra|all")," Shows the Output Config.")),(0,r.mdx)("p",null,"Example outputs:"),(0,r.mdx)("details",null,(0,r.mdx)("summary",null,"python my_app.py ",(0,r.mdx)("b",null,"--info defaults-tree")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title=""',title:'""'},":\n hydra/config:\n hydra/hydra_logging: default\n hydra/job_logging: default\n hydra/launcher: basic\n hydra/sweeper: basic\n hydra/output: default\n hydra/help: default\n hydra/hydra_help: default\n _self_\n config:\n server/apache:\n server/db: mysql\n _self_\n _self_\n"))),(0,r.mdx)("details",null,(0,r.mdx)("summary",null,"python my_app.py ",(0,r.mdx)("b",null,"--info defaults")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-text"},"Defaults List\n*************\n| Config path | Package | _self_ | Parent | \n-------------------------------------------------------------------------------\n| hydra/hydra_logging/default | hydra.hydra_logging | False | hydra/config |\n| hydra/job_logging/default | hydra.job_logging | False | hydra/config |\n| hydra/launcher/basic | hydra.launcher | False | hydra/config |\n| hydra/sweeper/basic | hydra.sweeper | False | hydra/config |\n| hydra/output/default | hydra | False | hydra/config |\n| hydra/help/default | hydra.help | False | hydra/config |\n| hydra/hydra_help/default | hydra.hydra_help | False | hydra/config |\n| hydra/config | hydra | True | |\n| server/db/mysql | server.db | False | server/apache |\n| server/apache | server | True | config |\n| config | | True | |\n-------------------------------------------------------------------------------\n"))),(0,r.mdx)("details",null,(0,r.mdx)("summary",null,"python my_app.py ",(0,r.mdx)("b",null,"--cfg job")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml"},"server:\n db:\n name: mysql\n name: apache\ndebug: false\n"))),(0,r.mdx)("h2",{id:"related-topics"},"Related topics"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("a",{parentName:"li",href:"/docs/1.1/advanced/overriding_packages"},"Packages")),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("a",{parentName:"li",href:"/docs/1.1/patterns/extending_configs"},"Common Patterns/Extending Configs")),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("a",{parentName:"li",href:"/docs/1.1/patterns/configuring_experiments"},"Common Patterns/Configuring Experiments")),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("a",{parentName:"li",href:"/docs/1.1/patterns/select_multiple_configs_from_config_group"},"Selecting multiple configs from a Config Group"))))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/07586c7f.a6a8c29b.js b/assets/js/07586c7f.a6a8c29b.js deleted file mode 100644 index dd146550d4..0000000000 --- a/assets/js/07586c7f.a6a8c29b.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[9021],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>m,MDXProvider:()=>c,mdx:()=>g,useMDXComponents:()=>p,withMDXComponents:()=>s});var t=a(96540);function l(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function r(){return r=Object.assign||function(e){for(var n=1;n=0||(l[a]=e[a]);return l}(e,n);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(l[a]=e[a])}return l}var m=t.createContext({}),s=function(e){return function(n){var a=p(n.components);return t.createElement(e,r({},n,{components:a}))}},p=function(e){var n=t.useContext(m),a=n;return e&&(a="function"==typeof e?e(n):d(d({},n),e)),a},c=function(e){var n=p(e.components);return t.createElement(m.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return t.createElement(t.Fragment,{},n)}},f=t.forwardRef((function(e,n){var a=e.components,l=e.mdxType,r=e.originalType,i=e.parentName,m=o(e,["components","mdxType","originalType","parentName"]),s=p(a),c=l,f=s["".concat(i,".").concat(c)]||s[c]||u[c]||r;return a?t.createElement(f,d(d({ref:n},m),{},{components:a})):t.createElement(f,d({ref:n},m))}));function g(e,n){var a=arguments,l=n&&n.mdxType;if("string"==typeof e||l){var r=a.length,i=new Array(r);i[0]=f;var d={};for(var o in n)hasOwnProperty.call(n,o)&&(d[o]=n[o]);d.originalType=e,d.mdxType="string"==typeof e?e:l,i[1]=d;for(var m=2;m{a.r(n),a.d(n,{contentTitle:()=>o,default:()=>c,frontMatter:()=>d,metadata:()=>m,toc:()=>s});var t=a(58168),l=a(98587),r=(a(96540),a(15680)),i=["components"],d={id:"defaults_list",title:"The Defaults List"},o=void 0,m={unversionedId:"advanced/defaults_list",id:"version-1.1/advanced/defaults_list",title:"The Defaults List",description:"Introduction",source:"@site/versioned_docs/version-1.1/advanced/defaults_list.md",sourceDirName:"advanced",slug:"/advanced/defaults_list",permalink:"/docs/1.1/advanced/defaults_list",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/advanced/defaults_list.md",tags:[],version:"1.1",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"defaults_list",title:"The Defaults List"},sidebar:"version-1.1/docs",previous:{title:"Extended Override syntax",permalink:"/docs/1.1/advanced/override_grammar/extended"},next:{title:"Packages",permalink:"/docs/1.1/advanced/overriding_packages"}},s=[{value:"Introduction",id:"introduction",children:[],level:2},{value:"An example",id:"an-example",children:[],level:2},{value:"Overriding Config Group options",id:"overriding-config-group-options",children:[],level:2},{value:"Composition order",id:"composition-order",children:[],level:2},{value:"Interpolation in the Defaults List",id:"interpolation-in-the-defaults-list",children:[{value:"Restrictions:",id:"restrictions",children:[],level:4}],level:2},{value:"Debugging the Defaults List",id:"debugging-the-defaults-list",children:[],level:2},{value:"Related topics",id:"related-topics",children:[],level:2}],p={toc:s};function c(e){var n=e.components,a=(0,l.A)(e,i);return(0,r.mdx)("wrapper",(0,t.A)({},p,a,{components:n,mdxType:"MDXLayout"}),(0,r.mdx)("h2",{id:"introduction"},"Introduction"),(0,r.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,r.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,r.mdx)("h5",{parentName:"div"},(0,r.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,r.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,r.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,r.mdx)("div",{parentName:"div",className:"admonition-content"},(0,r.mdx)("p",{parentName:"div"},"Many of the features described in this page are new. Please report any issues."))),(0,r.mdx)("p",null,"The Defaults List is a list in an input config that instructs Hydra how to build the output config.\nEach input config can have a Defaults List as a top level element. The Defaults List itself\nis not a part of output config."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Defaults List YAML syntax"',title:'"Defaults',List:!0,YAML:!0,'syntax"':!0},"defaults:\n (- CONFIG|GROUP_DEFAULT)*\n\nCONFIG : (CONFIG_GROUP/)?CONFIG_NAME(@PACKAGE)?\nGROUP_DEFAULT : [optional|override]? CONFIG_GROUP(@PACKAGE)?: OPTION\nOPTION : CONFIG_NAME|CONFIG_NAMES|null\n")),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"CONFIG")," : A config to use when creating the output config. e.g. ",(0,r.mdx)("inlineCode",{parentName:"p"},"db/mysql"),", ",(0,r.mdx)("inlineCode",{parentName:"p"},"db/mysql@backup"),"."),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"GROUP_DEFAULT")," : An ",(0,r.mdx)("em",{parentName:"p"},"overridable")," config. e.g. ",(0,r.mdx)("inlineCode",{parentName:"p"},"db: mysql"),", ",(0,r.mdx)("inlineCode",{parentName:"p"},"db@backup: mysql"),"."),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("strong",{parentName:"li"},(0,r.mdx)("em",{parentName:"strong"},"override"))," : Overrides the option of a previously defined GROUP_DEFAULT."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("strong",{parentName:"li"},(0,r.mdx)("em",{parentName:"strong"},"optional"))," : By default, an OPTION that do not exist causes an error; optional suppresses the error. "),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("strong",{parentName:"li"},(0,r.mdx)("em",{parentName:"strong"},"null"))," : A place-holder for a future override. If it is not overridden the entry is ignored.")),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"CONFIG_NAME"),": The name of a config, without the file system extension. e.g. ",(0,r.mdx)("inlineCode",{parentName:"p"},"mysql")," and not ",(0,r.mdx)("inlineCode",{parentName:"p"},"mysql.yaml"),"."),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"CONFIG_NAMES")," : A list of config names. e.g. ",(0,r.mdx)("inlineCode",{parentName:"p"},"[mysql, sqlite]")),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"CONFIG_GROUP")," : A path to a set of configs.",(0,r.mdx)("br",{parentName:"p"}),"\n","The path is relative to the containing config.\nIt can be made absolute by prefixing it with a ",(0,r.mdx)("inlineCode",{parentName:"p"},"/"),".",(0,r.mdx)("br",{parentName:"p"}),"\n","The path separator is ",(0,r.mdx)("inlineCode",{parentName:"p"},"/")," regardless of the operating system."),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"OPTION"),": The currently selected ",(0,r.mdx)("em",{parentName:"p"},"CONFIG_NAME")," or ",(0,r.mdx)("em",{parentName:"p"},"CONFIG_NAMES")," from a ",(0,r.mdx)("em",{parentName:"p"},"CONFIG_GROUP"),". "),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"PACKAGE")," : Where to place the content of the config within the output config.\nIt is relative to the Package of the containing config by default. See ",(0,r.mdx)("a",{parentName:"p",href:"/docs/1.1/advanced/overriding_packages"},"Packages"),"."),(0,r.mdx)("h2",{id:"an-example"},"An example"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Config directory structure"',title:'"Config',directory:!0,'structure"':!0},"\u251c\u2500\u2500 server\n\u2502 \u251c\u2500\u2500 db\n\u2502 \u2502 \u251c\u2500\u2500 mysql.yaml\n\u2502 \u2502 \u2514\u2500\u2500 sqlite.yaml\n\u2502 \u2514\u2500\u2500 apache.yaml\n\u2514\u2500\u2500 config.yaml\n")),(0,r.mdx)("p",null,"Input configs:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - server/apache\n\ndebug: false\n\n\n\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/apache.yaml"',title:'"server/apache.yaml"'},"defaults:\n - db: mysql\n\nname: apache\n\n\n\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/db/mysql.yaml"',title:'"server/db/mysql.yaml"'},"name: mysql\n")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/db/sqlite.yaml"',title:'"server/db/sqlite.yaml"'},"name: sqlite\n")))),(0,r.mdx)("p",null,"Output config:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py"',title:'"$',python:!0,'my_app.py"':!0},"server:\n db:\n name: mysql\n name: apache\ndebug: false\n")),(0,r.mdx)("h2",{id:"overriding-config-group-options"},"Overriding Config Group options"),(0,r.mdx)("p",null,"A Config Group's option can be overridden using a new ",(0,r.mdx)("em",{parentName:"p"},"GROUP_DEFAULT")," with the ",(0,r.mdx)("strong",{parentName:"p"},(0,r.mdx)("em",{parentName:"strong"},"override"))," keyword.\nIf a Group Default is overridden more than once, the last one, in depth first order, wins."),(0,r.mdx)("p",null,"Extending the previous example:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {3}',title:'"config.yaml"',"{3}":!0},"defaults:\n - server/apache\n - override server/db: sqlite\n\ndebug: false\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py" {2,3}',title:'"$',python:!0,'my_app.py"':!0,"{2,3}":!0},"server:\n db:\n name: sqlite\n name: apache\ndebug: false\n")))),(0,r.mdx)("p",null,"A Config Group's option can also be overridden via the command line. e.g: "),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre"},"$ python my_app.py server/db=sqlite\n")),(0,r.mdx)("h2",{id:"composition-order"},"Composition order"),(0,r.mdx)("p",null,"The Defaults List is ordered:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"If multiple configs define the same value, the last one wins."),(0,r.mdx)("li",{parentName:"ul"},"If multiple configs contribute to the same dictionary, the result is the combined dictionary.")),(0,r.mdx)("p",null,"By default, the content of a config is overriding the content of configs in the defaults list."),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {5}',title:'"config.yaml"',"{5}":!0},"defaults:\n - db: mysql \n\ndb:\n host: backup\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Result: db.host from config" {3}',title:'"Result:',"db.host":!0,from:!0,'config"':!0,"{3}":!0},"db:\n driver: mysql # db/mysql.yaml\n host: backup # config.yaml\n port: 3306 # db/mysql.yaml\n\n")))),(0,r.mdx)("p",null,"The ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," entry determines the relative position of ",(0,r.mdx)("strong",{parentName:"p"},"this")," config in the Defaults List.\nIf it is not specified, it is added automatically as the last item."),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {2,6}',title:'"config.yaml"',"{2,6}":!0},"defaults:\n - _self_\n - db: mysql # Overrides this config \n\ndb:\n host: backup\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Result: All values from db/mysql" {3}',title:'"Result:',All:!0,values:!0,from:!0,'db/mysql"':!0,"{3}":!0},"db:\n driver: mysql # db/mysql.yaml\n host: localhost # db/mysql.yaml\n port: 3306 # db/mysql.yaml\n\n\n")))),(0,r.mdx)("p",null,"With ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," at the top of the Defaults List, the host field defined in ",(0,r.mdx)("em",{parentName:"p"},"config.yaml")," now precedes the host field defined\nin ",(0,r.mdx)("em",{parentName:"p"},"db/mysql.yaml"),", and as a result is overridden."),(0,r.mdx)("h2",{id:"interpolation-in-the-defaults-list"},"Interpolation in the Defaults List"),(0,r.mdx)("p",null,"Config Group Options can be selected using interpolation."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - server: apache\n - db: mysql\n - combination_specific_config: ${server}_${db} # apache_mysql\n")),(0,r.mdx)("p",null,"Interpolation keys can be config groups with any @package overrides.",(0,r.mdx)("br",{parentName:"p"}),"\n","For example: ",(0,r.mdx)("inlineCode",{parentName:"p"},"${db/engine}"),", ",(0,r.mdx)("inlineCode",{parentName:"p"},"${db@backup}")),(0,r.mdx)("p",null,"The selected option for ",(0,r.mdx)("em",{parentName:"p"},"combination_specific_config")," depends on the final selected options for ",(0,r.mdx)("em",{parentName:"p"},"db")," and ",(0,r.mdx)("em",{parentName:"p"},"server"),".",(0,r.mdx)("br",{parentName:"p"}),"\n","e.g., If ",(0,r.mdx)("em",{parentName:"p"},"db")," is overridden to ",(0,r.mdx)("em",{parentName:"p"},"sqlite"),", ",(0,r.mdx)("em",{parentName:"p"},"combination_specific_config")," will become ",(0,r.mdx)("em",{parentName:"p"},"apache_sqlite"),"."),(0,r.mdx)("h4",{id:"restrictions"},"Restrictions:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Interpolation keys in the Defaults List cannot reference values in the Final Config Object (it does not yet exist)."),(0,r.mdx)("li",{parentName:"ul"},"Defaults List interpolation keys are absolute (even in nested configs)."),(0,r.mdx)("li",{parentName:"ul"},"The subtree expanded by an Interpolated Config may not contain Default List overrides.")),(0,r.mdx)("p",null,"See ",(0,r.mdx)("a",{parentName:"p",href:"/docs/1.1/patterns/specializing_config"},"Patterns/Specializing Configs")," for more information."),(0,r.mdx)("h2",{id:"debugging-the-defaults-list"},"Debugging the Defaults List"),(0,r.mdx)("p",null,"Hydra's config composition process is as follows:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"The Defaults Tree is created."),(0,r.mdx)("li",{parentName:"ul"},"The Final Defaults List is created via a DFS walk of the Defaults Tree."),(0,r.mdx)("li",{parentName:"ul"},"The Output Config is composed from the entries in the Final Defaults List.")),(0,r.mdx)("p",null,"You can inspect these artifacts via command line flags:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"--info defaults-tree")," shows the Defaults Tree."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"--info defaults")," Shows the Final Defaults List."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"--cfg job|hydra|all")," Shows the Output Config.")),(0,r.mdx)("p",null,"Example outputs:"),(0,r.mdx)("details",null,(0,r.mdx)("summary",null,"python my_app.py ",(0,r.mdx)("b",null,"--info defaults-tree")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title=""',title:'""'},":\n hydra/config:\n hydra/hydra_logging: default\n hydra/job_logging: default\n hydra/launcher: basic\n hydra/sweeper: basic\n hydra/output: default\n hydra/help: default\n hydra/hydra_help: default\n _self_\n config:\n server/apache:\n server/db: mysql\n _self_\n _self_\n"))),(0,r.mdx)("details",null,(0,r.mdx)("summary",null,"python my_app.py ",(0,r.mdx)("b",null,"--info defaults")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-text"},"Defaults List\n*************\n| Config path | Package | _self_ | Parent | \n-------------------------------------------------------------------------------\n| hydra/hydra_logging/default | hydra.hydra_logging | False | hydra/config |\n| hydra/job_logging/default | hydra.job_logging | False | hydra/config |\n| hydra/launcher/basic | hydra.launcher | False | hydra/config |\n| hydra/sweeper/basic | hydra.sweeper | False | hydra/config |\n| hydra/output/default | hydra | False | hydra/config |\n| hydra/help/default | hydra.help | False | hydra/config |\n| hydra/hydra_help/default | hydra.hydra_help | False | hydra/config |\n| hydra/config | hydra | True | |\n| server/db/mysql | server.db | False | server/apache |\n| server/apache | server | True | config |\n| config | | True | |\n-------------------------------------------------------------------------------\n"))),(0,r.mdx)("details",null,(0,r.mdx)("summary",null,"python my_app.py ",(0,r.mdx)("b",null,"--cfg job")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml"},"server:\n db:\n name: mysql\n name: apache\ndebug: false\n"))),(0,r.mdx)("h2",{id:"related-topics"},"Related topics"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("a",{parentName:"li",href:"/docs/1.1/advanced/overriding_packages"},"Packages")),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("a",{parentName:"li",href:"/docs/1.1/patterns/extending_configs"},"Common Patterns/Extending Configs")),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("a",{parentName:"li",href:"/docs/1.1/patterns/configuring_experiments"},"Common Patterns/Configuring Experiments")),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("a",{parentName:"li",href:"/docs/1.1/patterns/select_multiple_configs_from_config_group"},"Selecting multiple configs from a Config Group"))))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/0a4b398d.43c8f17a.js b/assets/js/0a4b398d.43c8f17a.js deleted file mode 100644 index e891269708..0000000000 --- a/assets/js/0a4b398d.43c8f17a.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[5908],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>m,MDXProvider:()=>d,mdx:()=>g,useMDXComponents:()=>c,withMDXComponents:()=>s});var r=t(96540);function a(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(a[t]=e[t]);return a}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(a[t]=e[t])}return a}var m=r.createContext({}),s=function(e){return function(n){var t=c(n.components);return r.createElement(e,i({},n,{components:t}))}},c=function(e){var n=r.useContext(m),t=n;return e&&(t="function"==typeof e?e(n):l(l({},n),e)),t},d=function(e){var n=c(e.components);return r.createElement(m.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},f=r.forwardRef((function(e,n){var t=e.components,a=e.mdxType,i=e.originalType,o=e.parentName,m=p(e,["components","mdxType","originalType","parentName"]),s=c(t),d=a,f=s["".concat(o,".").concat(d)]||s[d]||u[d]||i;return t?r.createElement(f,l(l({ref:n},m),{},{components:t})):r.createElement(f,l({ref:n},m))}));function g(e,n){var t=arguments,a=n&&n.mdxType;if("string"==typeof e||a){var i=t.length,o=new Array(i);o[0]=f;var l={};for(var p in n)hasOwnProperty.call(n,p)&&(l[p]=n[p]);l.originalType=e,l.mdxType="string"==typeof e?e:a,o[1]=l;for(var m=2;m{t.d(n,{A:()=>p,C:()=>m});var r=t(58168),a=t(96540),i=t(75489),o=t(44586),l=t(74098);function p(e){return a.createElement(i.default,(0,r.A)({},e,{to:(n=e.to,p=(0,l.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==p?void 0:p.name)?t:"current"]+n),target:"_blank"}));var n,t,p}function m(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return a.createElement(p,e,a.createElement("span",null,"\xa0"),a.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},52699:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>m,default:()=>u,frontMatter:()=>p,metadata:()=>s,toc:()=>c});var r=t(58168),a=t(98587),i=(t(96540),t(15680)),o=t(49595),l=["components"],p={id:"rerun",title:"Re-run a job from previous config",sidebar_label:"Re-run"},m=void 0,s={unversionedId:"experimental/rerun",id:"experimental/rerun",title:"Re-run a job from previous config",description:"This is an experimental feature. Please read through this page to understand what is supported.",source:"@site/docs/experimental/rerun.md",sourceDirName:"experimental",slug:"/experimental/rerun",permalink:"/docs/experimental/rerun",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/experimental/rerun.md",tags:[],version:"current",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"rerun",title:"Re-run a job from previous config",sidebar_label:"Re-run"},sidebar:"docs",previous:{title:"Callbacks",permalink:"/docs/experimental/callbacks"},next:{title:"Developer Guide Overview",permalink:"/docs/development/overview"}},c=[{value:"Important Notes",id:"important-notes",children:[],level:3}],d={toc:c};function u(e){var n=e.components,t=(0,a.A)(e,l);return(0,i.mdx)("wrapper",(0,r.A)({},d,t,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)(o.C,{text:"Example application",to:"examples/experimental/rerun",mdxType:"ExampleGithubLink"}),(0,i.mdx)("div",{className:"admonition admonition-caution alert alert--warning"},(0,i.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,i.mdx)("h5",{parentName:"div"},(0,i.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,i.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"16",height:"16",viewBox:"0 0 16 16"},(0,i.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"}))),"caution")),(0,i.mdx)("div",{parentName:"div",className:"admonition-content"},(0,i.mdx)("p",{parentName:"div"},"This is an experimental feature. Please read through this page to understand what is supported."))),(0,i.mdx)("p",null,"We use the example app linked above for demonstration. To save the configs for re-run, first use the experimental\nHydra Callback for saving the job info:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"hydra:\n callbacks:\n save_job_info:\n _target_: hydra.experimental.callbacks.PickleJobInfoCallback\n")),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Example function"',title:'"Example','function"':!0},'@hydra.main(version_base=None, config_path=".", config_name="config")\ndef my_app(cfg: DictConfig) -> None:\n log.info(f"output_dir={HydraConfig.get().runtime.output_dir}")\n log.info(f"cfg.foo={cfg.foo}")\n')),(0,i.mdx)("p",null,"Run the example app:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ python my_app.py\n[2022-03-16 14:51:30,905][hydra.experimental.pickle_job_info_callback][INFO] - Saving job configs in /Users/jieru/workspace/hydra/examples/experimental/outputs/2022-03-16/14-51-30/.hydra/config.pickle\n[2022-03-16 14:51:30,906][__main__][INFO] - Output_dir=/Users/jieru/workspace/hydra/examples/experimental/outputs/2022-03-16/14-51-30\n[2022-03-16 14:51:30,906][__main__][INFO] - cfg.foo=bar\n[2022-03-16 14:51:30,906][hydra.experimental.pickle_job_info_callback][INFO] - Saving job_return in /Users/jieru/workspace/hydra/examples/experimental/outputs/2022-03-16/14-51-30/.hydra/job_return.pickle\n")),(0,i.mdx)("p",null,"The Callback saves ",(0,i.mdx)("inlineCode",{parentName:"p"},"config.pickle")," in ",(0,i.mdx)("inlineCode",{parentName:"p"},".hydra")," sub dir, this is what we will use for rerun."),(0,i.mdx)("p",null,"Now rerun the app"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ OUTPUT_DIR=/Users/jieru/workspace/hydra/examples/experimental/outputs/2022-03-16/14-51-30/.hydra/\n$ python my_app.py --experimental-rerun $OUTPUT_DIR/config.pickle\n/Users/jieru/workspace/hydra/hydra/main.py:23: UserWarning: Experimental rerun CLI option.\n warnings.warn(msg, UserWarning)\n[2022-03-16 14:59:21,666][__main__][INFO] - Output_dir=/Users/jieru/workspace/hydra/examples/experimental/outputs/2022-03-16/14-51-30\n[2022-03-16 14:59:21,666][__main__][INFO] - cfg.foo=bar\n")),(0,i.mdx)("p",null,"You will notice ",(0,i.mdx)("inlineCode",{parentName:"p"},"my_app.log")," is updated with the logging from the second run, but Callbacks are not called this time. Read on to learn more."),(0,i.mdx)("h3",{id:"important-notes"},"Important Notes"),(0,i.mdx)("p",null,"This is an experimental feature. Please reach out if you have any question. "),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"Only single run is supported."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"--experimental-rerun")," cannot be used with other command-line options or overrides. They will simply be ignored."),(0,i.mdx)("li",{parentName:"ul"},"Rerun passes in a cfg_passthrough directly to your application, this means except for logging, no other ",(0,i.mdx)("inlineCode",{parentName:"li"},"hydra.main"),"\nfunctions are called (such as change working dir, or calling callbacks.) "),(0,i.mdx)("li",{parentName:"ul"},"The configs are preserved and reconstructed to the best efforts. Meaning we can only guarantee that the ",(0,i.mdx)("inlineCode",{parentName:"li"},"cfg")," object\nitself passed in by ",(0,i.mdx)("inlineCode",{parentName:"li"},"hydra.main")," stays the same across runs. However, configs are resolved lazily. Meaning we cannot\nguarantee your application will behave the same if your application resolves configs during run time. In the following example,\n",(0,i.mdx)("inlineCode",{parentName:"li"},"cfg.time_now")," will resolve to different value every run.")),(0,i.mdx)("div",{className:"row"},(0,i.mdx)("div",{className:"col col--5"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"time_now: ${now:%H-%M-%S}\n\n\n\n"))),(0,i.mdx)("div",{className:"col col--7"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Example function"',title:'"Example','function"':!0},'@hydra.main(version_base=None, config_path=".", config_name="config")\ndef my_app(cfg: DictConfig) -> None:\n val = cfg.time_now\n # the rest of the application\n')))))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/0a4b398d.cca14399.js b/assets/js/0a4b398d.cca14399.js new file mode 100644 index 0000000000..87e7a59068 --- /dev/null +++ b/assets/js/0a4b398d.cca14399.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[5908],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>m,MDXProvider:()=>d,mdx:()=>g,useMDXComponents:()=>c,withMDXComponents:()=>s});var r=t(96540);function a(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(a[t]=e[t]);return a}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(a[t]=e[t])}return a}var m=r.createContext({}),s=function(e){return function(n){var t=c(n.components);return r.createElement(e,i({},n,{components:t}))}},c=function(e){var n=r.useContext(m),t=n;return e&&(t="function"==typeof e?e(n):l(l({},n),e)),t},d=function(e){var n=c(e.components);return r.createElement(m.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},f=r.forwardRef((function(e,n){var t=e.components,a=e.mdxType,i=e.originalType,o=e.parentName,m=p(e,["components","mdxType","originalType","parentName"]),s=c(t),d=a,f=s["".concat(o,".").concat(d)]||s[d]||u[d]||i;return t?r.createElement(f,l(l({ref:n},m),{},{components:t})):r.createElement(f,l({ref:n},m))}));function g(e,n){var t=arguments,a=n&&n.mdxType;if("string"==typeof e||a){var i=t.length,o=new Array(i);o[0]=f;var l={};for(var p in n)hasOwnProperty.call(n,p)&&(l[p]=n[p]);l.originalType=e,l.mdxType="string"==typeof e?e:a,o[1]=l;for(var m=2;m{t.d(n,{A:()=>p,C:()=>m});var r=t(58168),a=t(96540),i=t(75489),o=t(44586),l=t(74098);function p(e){return a.createElement(i.default,(0,r.A)({},e,{to:(n=e.to,p=(0,l.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==p?void 0:p.name)?t:"current"]+n),target:"_blank"}));var n,t,p}function m(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return a.createElement(p,e,a.createElement("span",null,"\xa0"),a.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},52699:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>m,default:()=>u,frontMatter:()=>p,metadata:()=>s,toc:()=>c});var r=t(58168),a=t(98587),i=(t(96540),t(15680)),o=t(49595),l=["components"],p={id:"rerun",title:"Re-run a job from previous config",sidebar_label:"Re-run"},m=void 0,s={unversionedId:"experimental/rerun",id:"experimental/rerun",title:"Re-run a job from previous config",description:"This is an experimental feature. Please read through this page to understand what is supported.",source:"@site/docs/experimental/rerun.md",sourceDirName:"experimental",slug:"/experimental/rerun",permalink:"/docs/experimental/rerun",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/experimental/rerun.md",tags:[],version:"current",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"rerun",title:"Re-run a job from previous config",sidebar_label:"Re-run"},sidebar:"docs",previous:{title:"Callbacks",permalink:"/docs/experimental/callbacks"},next:{title:"Developer Guide Overview",permalink:"/docs/development/overview"}},c=[{value:"Important Notes",id:"important-notes",children:[],level:3}],d={toc:c};function u(e){var n=e.components,t=(0,a.A)(e,l);return(0,i.mdx)("wrapper",(0,r.A)({},d,t,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)(o.C,{text:"Example application",to:"examples/experimental/rerun",mdxType:"ExampleGithubLink"}),(0,i.mdx)("div",{className:"admonition admonition-caution alert alert--warning"},(0,i.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,i.mdx)("h5",{parentName:"div"},(0,i.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,i.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"16",height:"16",viewBox:"0 0 16 16"},(0,i.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"}))),"caution")),(0,i.mdx)("div",{parentName:"div",className:"admonition-content"},(0,i.mdx)("p",{parentName:"div"},"This is an experimental feature. Please read through this page to understand what is supported."))),(0,i.mdx)("p",null,"We use the example app linked above for demonstration. To save the configs for re-run, first use the experimental\nHydra Callback for saving the job info:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"hydra:\n callbacks:\n save_job_info:\n _target_: hydra.experimental.callbacks.PickleJobInfoCallback\n")),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Example function"',title:'"Example','function"':!0},'@hydra.main(version_base=None, config_path=".", config_name="config")\ndef my_app(cfg: DictConfig) -> None:\n log.info(f"output_dir={HydraConfig.get().runtime.output_dir}")\n log.info(f"cfg.foo={cfg.foo}")\n')),(0,i.mdx)("p",null,"Run the example app:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ python my_app.py\n[2022-03-16 14:51:30,905][hydra.experimental.pickle_job_info_callback][INFO] - Saving job configs in /Users/jieru/workspace/hydra/examples/experimental/outputs/2022-03-16/14-51-30/.hydra/config.pickle\n[2022-03-16 14:51:30,906][__main__][INFO] - Output_dir=/Users/jieru/workspace/hydra/examples/experimental/outputs/2022-03-16/14-51-30\n[2022-03-16 14:51:30,906][__main__][INFO] - cfg.foo=bar\n[2022-03-16 14:51:30,906][hydra.experimental.pickle_job_info_callback][INFO] - Saving job_return in /Users/jieru/workspace/hydra/examples/experimental/outputs/2022-03-16/14-51-30/.hydra/job_return.pickle\n")),(0,i.mdx)("p",null,"The Callback saves ",(0,i.mdx)("inlineCode",{parentName:"p"},"config.pickle")," in ",(0,i.mdx)("inlineCode",{parentName:"p"},".hydra")," sub dir, this is what we will use for rerun."),(0,i.mdx)("p",null,"Now rerun the app"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ OUTPUT_DIR=/Users/jieru/workspace/hydra/examples/experimental/outputs/2022-03-16/14-51-30/.hydra/\n$ python my_app.py --experimental-rerun $OUTPUT_DIR/config.pickle\n/Users/jieru/workspace/hydra/hydra/main.py:23: UserWarning: Experimental rerun CLI option.\n warnings.warn(msg, UserWarning)\n[2022-03-16 14:59:21,666][__main__][INFO] - Output_dir=/Users/jieru/workspace/hydra/examples/experimental/outputs/2022-03-16/14-51-30\n[2022-03-16 14:59:21,666][__main__][INFO] - cfg.foo=bar\n")),(0,i.mdx)("p",null,"You will notice ",(0,i.mdx)("inlineCode",{parentName:"p"},"my_app.log")," is updated with the logging from the second run, but Callbacks are not called this time. Read on to learn more."),(0,i.mdx)("h3",{id:"important-notes"},"Important Notes"),(0,i.mdx)("p",null,"This is an experimental feature. Please reach out if you have any question. "),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"Only single run is supported."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"--experimental-rerun")," cannot be used with other command-line options or overrides. They will simply be ignored."),(0,i.mdx)("li",{parentName:"ul"},"Rerun passes in a cfg_passthrough directly to your application, this means except for logging, no other ",(0,i.mdx)("inlineCode",{parentName:"li"},"hydra.main"),"\nfunctions are called (such as change working dir, or calling callbacks.) "),(0,i.mdx)("li",{parentName:"ul"},"The configs are preserved and reconstructed to the best efforts. Meaning we can only guarantee that the ",(0,i.mdx)("inlineCode",{parentName:"li"},"cfg")," object\nitself passed in by ",(0,i.mdx)("inlineCode",{parentName:"li"},"hydra.main")," stays the same across runs. However, configs are resolved lazily. Meaning we cannot\nguarantee your application will behave the same if your application resolves configs during run time. In the following example,\n",(0,i.mdx)("inlineCode",{parentName:"li"},"cfg.time_now")," will resolve to different value every run.")),(0,i.mdx)("div",{className:"row"},(0,i.mdx)("div",{className:"col col--5"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"time_now: ${now:%H-%M-%S}\n\n\n\n"))),(0,i.mdx)("div",{className:"col col--7"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Example function"',title:'"Example','function"':!0},'@hydra.main(version_base=None, config_path=".", config_name="config")\ndef my_app(cfg: DictConfig) -> None:\n val = cfg.time_now\n # the rest of the application\n')))))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/0a7b70ce.130cc7f3.js b/assets/js/0a7b70ce.130cc7f3.js deleted file mode 100644 index 64d5e16f56..0000000000 --- a/assets/js/0a7b70ce.130cc7f3.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3940],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>l,MDXProvider:()=>u,mdx:()=>h,useMDXComponents:()=>d,withMDXComponents:()=>p});var i=n(96540);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(i=0;i=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var l=i.createContext({}),p=function(e){return function(t){var n=d(t.components);return i.createElement(e,a({},t,{components:n}))}},d=function(e){var t=i.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):c(c({},t),e)),n},u=function(e){var t=d(e.components);return i.createElement(l.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return i.createElement(i.Fragment,{},t)}},f=i.forwardRef((function(e,t){var n=e.components,r=e.mdxType,a=e.originalType,o=e.parentName,l=s(e,["components","mdxType","originalType","parentName"]),p=d(n),u=r,f=p["".concat(o,".").concat(u)]||p[u]||m[u]||a;return n?i.createElement(f,c(c({ref:t},l),{},{components:n})):i.createElement(f,c({ref:t},l))}));function h(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var a=n.length,o=new Array(a);o[0]=f;var c={};for(var s in t)hasOwnProperty.call(t,s)&&(c[s]=t[s]);c.originalType=e,c.mdxType="string"==typeof e?e:r,o[1]=c;for(var l=2;l{n.d(t,{A:()=>s,C:()=>l});var i=n(58168),r=n(96540),a=n(75489),o=n(44586),c=n(74098);function s(e){return r.createElement(a.default,(0,i.A)({},e,{to:(t=e.to,s=(0,c.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==s?void 0:s.name)?n:"current"]+t),target:"_blank"}));var t,n,s}function l(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return r.createElement(s,e,r.createElement("span",null,"\xa0"),r.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},63835:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>l,default:()=>m,frontMatter:()=>s,metadata:()=>p,toc:()=>d});var i=n(58168),r=n(98587),a=(n(96540),n(15680)),o=n(49595),c=["components"],s={id:"unit_testing",title:"Hydra in Unit Tests"},l=void 0,p={unversionedId:"advanced/unit_testing",id:"version-1.2/advanced/unit_testing",title:"Hydra in Unit Tests",description:"Use initialize(), initializeconfigmodule() or initializeconfigdir() in conjunction with compose()",source:"@site/versioned_docs/version-1.2/advanced/unit_testing.md",sourceDirName:"advanced",slug:"/advanced/unit_testing",permalink:"/docs/1.2/advanced/unit_testing",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/advanced/unit_testing.md",tags:[],version:"1.2",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"unit_testing",title:"Hydra in Unit Tests"},sidebar:"docs",previous:{title:"Hydra in Jupyter Notebooks",permalink:"/docs/1.2/advanced/jupyter_notebooks"},next:{title:"Introduction",permalink:"/docs/1.2/experimental/intro"}},d=[],u={toc:d};function m(e){var t=e.components,n=(0,r.A)(e,c);return(0,a.mdx)("wrapper",(0,i.A)({},u,n,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)("p",null,"Use ",(0,a.mdx)("inlineCode",{parentName:"p"},"initialize()"),", ",(0,a.mdx)("inlineCode",{parentName:"p"},"initialize_config_module()")," or ",(0,a.mdx)("inlineCode",{parentName:"p"},"initialize_config_dir()")," in conjunction with ",(0,a.mdx)("inlineCode",{parentName:"p"},"compose()"),"\nto compose configs inside your unit tests.",(0,a.mdx)("br",{parentName:"p"}),"\n","Be sure to read the ",(0,a.mdx)("a",{parentName:"p",href:"/docs/1.2/advanced/compose_api"},"Compose API documentation"),"."),(0,a.mdx)("p",null,"The Hydra example application contains an ",(0,a.mdx)(o.A,{to:"examples/advanced/hydra_app_example/tests/test_example.py",mdxType:"GithubLink"},"example test"),"."),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Testing example with initialize()"',title:'"Testing',example:!0,with:!0,'initialize()"':!0},'from hydra import initialize, compose\n# 1. initialize will add config_path the config search path within the context\n# 2. The module with your configs should be importable. \n# it needs to have a __init__.py (can be empty).\n# 3. THe config path is relative to the file calling initialize (this file)\ndef test_with_initialize() -> None:\n with initialize(version_base=None, config_path="../hydra_app/conf"):\n # config is relative to a module\n cfg = compose(config_name="config", overrides=["app.user=test_user"])\n assert cfg == {\n "app": {"user": "test_user", "num1": 10, "num2": 20},\n "db": {"host": "localhost", "port": 3306},\n }\n')),(0,a.mdx)("p",null,"For an idea about how to modify Hydra's search path when using ",(0,a.mdx)("inlineCode",{parentName:"p"},"compose")," in\nunit tests, see the page on\n",(0,a.mdx)("a",{parentName:"p",href:"/docs/1.2/advanced/search_path#overriding-hydrasearchpath-config"},"overriding the ",(0,a.mdx)("inlineCode",{parentName:"a"},"hydra.searchpath")," config"),"."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/0a7b70ce.c804a0d8.js b/assets/js/0a7b70ce.c804a0d8.js new file mode 100644 index 0000000000..e7467a4d6e --- /dev/null +++ b/assets/js/0a7b70ce.c804a0d8.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3940],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>l,MDXProvider:()=>m,mdx:()=>h,useMDXComponents:()=>d,withMDXComponents:()=>p});var i=n(96540);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(i=0;i=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var l=i.createContext({}),p=function(e){return function(t){var n=d(t.components);return i.createElement(e,a({},t,{components:n}))}},d=function(e){var t=i.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):c(c({},t),e)),n},m=function(e){var t=d(e.components);return i.createElement(l.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return i.createElement(i.Fragment,{},t)}},f=i.forwardRef((function(e,t){var n=e.components,r=e.mdxType,a=e.originalType,o=e.parentName,l=s(e,["components","mdxType","originalType","parentName"]),p=d(n),m=r,f=p["".concat(o,".").concat(m)]||p[m]||u[m]||a;return n?i.createElement(f,c(c({ref:t},l),{},{components:n})):i.createElement(f,c({ref:t},l))}));function h(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var a=n.length,o=new Array(a);o[0]=f;var c={};for(var s in t)hasOwnProperty.call(t,s)&&(c[s]=t[s]);c.originalType=e,c.mdxType="string"==typeof e?e:r,o[1]=c;for(var l=2;l{n.d(t,{A:()=>s,C:()=>l});var i=n(58168),r=n(96540),a=n(75489),o=n(44586),c=n(74098);function s(e){return r.createElement(a.default,(0,i.A)({},e,{to:(t=e.to,s=(0,c.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==s?void 0:s.name)?n:"current"]+t),target:"_blank"}));var t,n,s}function l(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return r.createElement(s,e,r.createElement("span",null,"\xa0"),r.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},63835:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>l,default:()=>u,frontMatter:()=>s,metadata:()=>p,toc:()=>d});var i=n(58168),r=n(98587),a=(n(96540),n(15680)),o=n(49595),c=["components"],s={id:"unit_testing",title:"Hydra in Unit Tests"},l=void 0,p={unversionedId:"advanced/unit_testing",id:"version-1.2/advanced/unit_testing",title:"Hydra in Unit Tests",description:"Use initialize(), initializeconfigmodule() or initializeconfigdir() in conjunction with compose()",source:"@site/versioned_docs/version-1.2/advanced/unit_testing.md",sourceDirName:"advanced",slug:"/advanced/unit_testing",permalink:"/docs/1.2/advanced/unit_testing",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/advanced/unit_testing.md",tags:[],version:"1.2",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"unit_testing",title:"Hydra in Unit Tests"},sidebar:"docs",previous:{title:"Hydra in Jupyter Notebooks",permalink:"/docs/1.2/advanced/jupyter_notebooks"},next:{title:"Introduction",permalink:"/docs/1.2/experimental/intro"}},d=[],m={toc:d};function u(e){var t=e.components,n=(0,r.A)(e,c);return(0,a.mdx)("wrapper",(0,i.A)({},m,n,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)("p",null,"Use ",(0,a.mdx)("inlineCode",{parentName:"p"},"initialize()"),", ",(0,a.mdx)("inlineCode",{parentName:"p"},"initialize_config_module()")," or ",(0,a.mdx)("inlineCode",{parentName:"p"},"initialize_config_dir()")," in conjunction with ",(0,a.mdx)("inlineCode",{parentName:"p"},"compose()"),"\nto compose configs inside your unit tests.",(0,a.mdx)("br",{parentName:"p"}),"\n","Be sure to read the ",(0,a.mdx)("a",{parentName:"p",href:"/docs/1.2/advanced/compose_api"},"Compose API documentation"),"."),(0,a.mdx)("p",null,"The Hydra example application contains an ",(0,a.mdx)(o.A,{to:"examples/advanced/hydra_app_example/tests/test_example.py",mdxType:"GithubLink"},"example test"),"."),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Testing example with initialize()"',title:'"Testing',example:!0,with:!0,'initialize()"':!0},'from hydra import initialize, compose\n# 1. initialize will add config_path the config search path within the context\n# 2. The module with your configs should be importable. \n# it needs to have a __init__.py (can be empty).\n# 3. THe config path is relative to the file calling initialize (this file)\ndef test_with_initialize() -> None:\n with initialize(version_base=None, config_path="../hydra_app/conf"):\n # config is relative to a module\n cfg = compose(config_name="config", overrides=["app.user=test_user"])\n assert cfg == {\n "app": {"user": "test_user", "num1": 10, "num2": 20},\n "db": {"host": "localhost", "port": 3306},\n }\n')),(0,a.mdx)("p",null,"For an idea about how to modify Hydra's search path when using ",(0,a.mdx)("inlineCode",{parentName:"p"},"compose")," in\nunit tests, see the page on\n",(0,a.mdx)("a",{parentName:"p",href:"/docs/1.2/advanced/search_path#overriding-hydrasearchpath-config"},"overriding the ",(0,a.mdx)("inlineCode",{parentName:"a"},"hydra.searchpath")," config"),"."))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/0aa416e4.700fba1e.js b/assets/js/0aa416e4.700fba1e.js new file mode 100644 index 0000000000..5b202676a2 --- /dev/null +++ b/assets/js/0aa416e4.700fba1e.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[5071],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>p,MDXProvider:()=>d,mdx:()=>x,useMDXComponents:()=>c,withMDXComponents:()=>s});var a=t(96540);function r(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(r[t]=e[t]);return r}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(r[t]=e[t])}return r}var p=a.createContext({}),s=function(e){return function(n){var t=c(n.components);return a.createElement(e,i({},n,{components:t}))}},c=function(e){var n=a.useContext(p),t=n;return e&&(t="function"==typeof e?e(n):m(m({},n),e)),t},d=function(e){var n=c(e.components);return a.createElement(p.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},g=a.forwardRef((function(e,n){var t=e.components,r=e.mdxType,i=e.originalType,l=e.parentName,p=o(e,["components","mdxType","originalType","parentName"]),s=c(t),d=r,g=s["".concat(l,".").concat(d)]||s[d]||u[d]||i;return t?a.createElement(g,m(m({ref:n},p),{},{components:t})):a.createElement(g,m({ref:n},p))}));function x(e,n){var t=arguments,r=n&&n.mdxType;if("string"==typeof e||r){var i=t.length,l=new Array(i);l[0]=g;var m={};for(var o in n)hasOwnProperty.call(n,o)&&(m[o]=n[o]);m.originalType=e,m.mdxType="string"==typeof e?e:r,l[1]=m;for(var p=2;p{t.d(n,{A:()=>o,C:()=>p});var a=t(58168),r=t(96540),i=t(75489),l=t(44586),m=t(74098);function o(e){return r.createElement(i.default,(0,a.A)({},e,{to:(n=e.to,o=(0,m.useActiveVersion)(),(0,l.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==o?void 0:o.name)?t:"current"]+n),target:"_blank"}));var n,t,o}function p(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return r.createElement(o,e,r.createElement("span",null,"\xa0"),r.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},17561:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>p,default:()=>u,frontMatter:()=>o,metadata:()=>s,toc:()=>c});var a=t(58168),r=t(98587),i=(t(96540),t(15680)),l=t(49595),m=["components"],o={id:"configuring_experiments",title:"Configuring Experiments"},p=void 0,s={unversionedId:"patterns/configuring_experiments",id:"version-1.2/patterns/configuring_experiments",title:"Configuring Experiments",description:"Problem",source:"@site/versioned_docs/version-1.2/patterns/configuring_experiments.md",sourceDirName:"patterns",slug:"/patterns/configuring_experiments",permalink:"/docs/1.2/patterns/configuring_experiments",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/patterns/configuring_experiments.md",tags:[],version:"1.2",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"configuring_experiments",title:"Configuring Experiments"},sidebar:"docs",previous:{title:"Extending Configs",permalink:"/docs/1.2/patterns/extending_configs"},next:{title:"Configuring Plugins",permalink:"/docs/1.2/patterns/configuring_plugins"}},c=[{value:"Problem",id:"problem",children:[],level:3},{value:"Solution",id:"solution",children:[],level:3},{value:"Example",id:"example",children:[],level:3},{value:"Sweeping over experiments",id:"sweeping-over-experiments",children:[],level:3}],d={toc:c};function u(e){var n=e.components,t=(0,r.A)(e,m);return(0,i.mdx)("wrapper",(0,a.A)({},d,t,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)(l.C,{text:"Example application",to:"examples/patterns/configuring_experiments",mdxType:"ExampleGithubLink"}),(0,i.mdx)("h3",{id:"problem"},"Problem"),(0,i.mdx)("p",null,"A common problem is maintaining multiple configurations of an application. This can get especially\ntedious when the configuration differences span multiple dimensions.\nThis pattern shows how to cleanly support multiple configurations, with each configuration file only specifying\nthe changes to the master (default) configuration."),(0,i.mdx)("h3",{id:"solution"},"Solution"),(0,i.mdx)("p",null,"Create a config file specifying the overrides to the default configuration, and then call it via the command line.\ne.g. ",(0,i.mdx)("inlineCode",{parentName:"p"},"$ python my_app.py +experiment=fast_mode"),"."),(0,i.mdx)("p",null,"To avoid clutter, we place the experiment config files in dedicated config group called ",(0,i.mdx)("em",{parentName:"p"},"experiment"),"."),(0,i.mdx)("h3",{id:"example"},"Example"),(0,i.mdx)("p",null,"In this example, we will create configurations for each of the server and database pairings that we want to benchmark."),(0,i.mdx)("p",null,"The default configuration is:"),(0,i.mdx)("div",{className:"row"},(0,i.mdx)("div",{className:"col col--4"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - db: mysql\n - server: apache\n\n\n\n\n\n"))),(0,i.mdx)("div",{className:"col col--4"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml"',title:'"db/mysql.yaml"'},"name: mysql\n")),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/apache.yaml"',title:'"server/apache.yaml"'},"name: apache\nport: 80\n"))),(0,i.mdx)("div",{className:"col col--4"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/sqlite.yaml"',title:'"db/sqlite.yaml"'},"name: sqlite\n")),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/nginx.yaml"',title:'"server/nginx.yaml"'},"name: nginx\nport: 80\n")))),(0,i.mdx)("div",{className:"row"},(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Directory structure"',title:'"Directory','structure"':!0},"\u251c\u2500\u2500 config.yaml\n\u251c\u2500\u2500 db\n\u2502 \u251c\u2500\u2500 mysql.yaml\n\u2502 \u2514\u2500\u2500 sqlite.yaml\n\u2514\u2500\u2500 server\n \u251c\u2500\u2500 apache.yaml\n \u2514\u2500\u2500 nginx.yaml\n"))),(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py"',title:'"$',python:!0,'my_app.py"':!0},"db:\n name: mysql\nserver:\n name: apache\n port: 80\n\n\n")))),(0,i.mdx)("p",null,"The benchmark config files specify the deltas from the default configuration:"),(0,i.mdx)("div",{className:"row"},(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="experiment/aplite.yaml"',title:'"experiment/aplite.yaml"'},"# @package _global_\ndefaults:\n - override /db: sqlite\n \n \nserver:\n port: 8080\n"))),(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="experiment/nglite.yaml"',title:'"experiment/nglite.yaml"'},"# @package _global_\ndefaults:\n - override /db: sqlite\n - override /server: nginx\n \nserver:\n port: 8080\n")))),(0,i.mdx)("div",{className:"row"},(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py +experiment=aplite"',title:'"$',python:!0,"my_app.py":!0,"+experiment":'aplite"'},"db:\n name: sqlite\nserver:\n name: apache\n port: 8080\n"))),(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py +experiment=nglite"',title:'"$',python:!0,"my_app.py":!0,"+experiment":'nglite"'},"db:\n name: sqlite\nserver:\n name: nginx\n port: 8080\n")))),(0,i.mdx)("p",null,"Key concepts:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"#"," @package ","_","global","_"),(0,i.mdx)("br",{parentName:"li"}),"Changes specified in this config should be interpreted as relative to the ","_","global","_"," package.",(0,i.mdx)("br",{parentName:"li"}),"We could instead place ",(0,i.mdx)("em",{parentName:"li"},"nglite.yaml")," and ",(0,i.mdx)("em",{parentName:"li"},"aplite.yaml")," next to ",(0,i.mdx)("em",{parentName:"li"},"config.yaml")," and omit this line."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"The overrides of /db and /server are absolute paths."),(0,i.mdx)("br",{parentName:"li"}),"This is necessary because they are outside of the experiment directory. ")),(0,i.mdx)("p",null,"Running the experiments from the command line requires prefixing the experiment choice with a ",(0,i.mdx)("inlineCode",{parentName:"p"},"+"),".\nThe experiment config group is an addition, not an override."),(0,i.mdx)("h3",{id:"sweeping-over-experiments"},"Sweeping over experiments"),(0,i.mdx)("p",null,"This approach also enables sweeping over those experiments to easily compare their results:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="$ python my_app.py --multirun +experiment=aplite,nglite"',title:'"$',python:!0,"my_app.py":!0,"--multirun":!0,"+experiment":'aplite,nglite"'},"[HYDRA] Launching 2 jobs locally\n[HYDRA] #0 : +experiment=aplite\ndb:\n name: sqlite\nserver:\n name: apache\n port: 8080\n\n[HYDRA] #1 : +experiment=nglite\ndb:\n name: sqlite\nserver:\n name: nginx\n port: 8080\n")),(0,i.mdx)("p",null,"To run all the experiments, use the ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.2/advanced/override_grammar/extended#glob-choice-sweep"},"glob")," syntax:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text",metastring:"title=\"$ python my_app.py --multirun '+experiment=glob(*)'\"",title:'"$',python:!0,"my_app.py":!0,"--multirun":!0,"'+experiment":"glob(*)'\""},"[HYDRA] #0 : +experiment=aplite\n...\n[HYDRA] #1 : +experiment=nglite\n...\n")))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/0aa416e4.e19540f1.js b/assets/js/0aa416e4.e19540f1.js deleted file mode 100644 index add731847d..0000000000 --- a/assets/js/0aa416e4.e19540f1.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[5071],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>p,MDXProvider:()=>d,mdx:()=>x,useMDXComponents:()=>c,withMDXComponents:()=>s});var a=t(96540);function r(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(r[t]=e[t]);return r}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(r[t]=e[t])}return r}var p=a.createContext({}),s=function(e){return function(n){var t=c(n.components);return a.createElement(e,i({},n,{components:t}))}},c=function(e){var n=a.useContext(p),t=n;return e&&(t="function"==typeof e?e(n):m(m({},n),e)),t},d=function(e){var n=c(e.components);return a.createElement(p.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},g=a.forwardRef((function(e,n){var t=e.components,r=e.mdxType,i=e.originalType,l=e.parentName,p=o(e,["components","mdxType","originalType","parentName"]),s=c(t),d=r,g=s["".concat(l,".").concat(d)]||s[d]||u[d]||i;return t?a.createElement(g,m(m({ref:n},p),{},{components:t})):a.createElement(g,m({ref:n},p))}));function x(e,n){var t=arguments,r=n&&n.mdxType;if("string"==typeof e||r){var i=t.length,l=new Array(i);l[0]=g;var m={};for(var o in n)hasOwnProperty.call(n,o)&&(m[o]=n[o]);m.originalType=e,m.mdxType="string"==typeof e?e:r,l[1]=m;for(var p=2;p{t.d(n,{A:()=>o,C:()=>p});var a=t(58168),r=t(96540),i=t(75489),l=t(44586),m=t(74098);function o(e){return r.createElement(i.default,(0,a.A)({},e,{to:(n=e.to,o=(0,m.useActiveVersion)(),(0,l.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==o?void 0:o.name)?t:"current"]+n),target:"_blank"}));var n,t,o}function p(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return r.createElement(o,e,r.createElement("span",null,"\xa0"),r.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},17561:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>p,default:()=>u,frontMatter:()=>o,metadata:()=>s,toc:()=>c});var a=t(58168),r=t(98587),i=(t(96540),t(15680)),l=t(49595),m=["components"],o={id:"configuring_experiments",title:"Configuring Experiments"},p=void 0,s={unversionedId:"patterns/configuring_experiments",id:"version-1.2/patterns/configuring_experiments",title:"Configuring Experiments",description:"Problem",source:"@site/versioned_docs/version-1.2/patterns/configuring_experiments.md",sourceDirName:"patterns",slug:"/patterns/configuring_experiments",permalink:"/docs/1.2/patterns/configuring_experiments",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/patterns/configuring_experiments.md",tags:[],version:"1.2",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"configuring_experiments",title:"Configuring Experiments"},sidebar:"docs",previous:{title:"Extending Configs",permalink:"/docs/1.2/patterns/extending_configs"},next:{title:"Configuring Plugins",permalink:"/docs/1.2/patterns/configuring_plugins"}},c=[{value:"Problem",id:"problem",children:[],level:3},{value:"Solution",id:"solution",children:[],level:3},{value:"Example",id:"example",children:[],level:3},{value:"Sweeping over experiments",id:"sweeping-over-experiments",children:[],level:3}],d={toc:c};function u(e){var n=e.components,t=(0,r.A)(e,m);return(0,i.mdx)("wrapper",(0,a.A)({},d,t,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)(l.C,{text:"Example application",to:"examples/patterns/configuring_experiments",mdxType:"ExampleGithubLink"}),(0,i.mdx)("h3",{id:"problem"},"Problem"),(0,i.mdx)("p",null,"A common problem is maintaining multiple configurations of an application. This can get especially\ntedious when the configuration differences span multiple dimensions.\nThis pattern shows how to cleanly support multiple configurations, with each configuration file only specifying\nthe changes to the master (default) configuration."),(0,i.mdx)("h3",{id:"solution"},"Solution"),(0,i.mdx)("p",null,"Create a config file specifying the overrides to the default configuration, and then call it via the command line.\ne.g. ",(0,i.mdx)("inlineCode",{parentName:"p"},"$ python my_app.py +experiment=fast_mode"),"."),(0,i.mdx)("p",null,"To avoid clutter, we place the experiment config files in dedicated config group called ",(0,i.mdx)("em",{parentName:"p"},"experiment"),"."),(0,i.mdx)("h3",{id:"example"},"Example"),(0,i.mdx)("p",null,"In this example, we will create configurations for each of the server and database pairings that we want to benchmark."),(0,i.mdx)("p",null,"The default configuration is:"),(0,i.mdx)("div",{className:"row"},(0,i.mdx)("div",{className:"col col--4"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - db: mysql\n - server: apache\n\n\n\n\n\n"))),(0,i.mdx)("div",{className:"col col--4"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml"',title:'"db/mysql.yaml"'},"name: mysql\n")),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/apache.yaml"',title:'"server/apache.yaml"'},"name: apache\nport: 80\n"))),(0,i.mdx)("div",{className:"col col--4"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/sqlite.yaml"',title:'"db/sqlite.yaml"'},"name: sqlite\n")),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/nginx.yaml"',title:'"server/nginx.yaml"'},"name: nginx\nport: 80\n")))),(0,i.mdx)("div",{className:"row"},(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Directory structure"',title:'"Directory','structure"':!0},"\u251c\u2500\u2500 config.yaml\n\u251c\u2500\u2500 db\n\u2502 \u251c\u2500\u2500 mysql.yaml\n\u2502 \u2514\u2500\u2500 sqlite.yaml\n\u2514\u2500\u2500 server\n \u251c\u2500\u2500 apache.yaml\n \u2514\u2500\u2500 nginx.yaml\n"))),(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py"',title:'"$',python:!0,'my_app.py"':!0},"db:\n name: mysql\nserver:\n name: apache\n port: 80\n\n\n")))),(0,i.mdx)("p",null,"The benchmark config files specify the deltas from the default configuration:"),(0,i.mdx)("div",{className:"row"},(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="experiment/aplite.yaml"',title:'"experiment/aplite.yaml"'},"# @package _global_\ndefaults:\n - override /db: sqlite\n \n \nserver:\n port: 8080\n"))),(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="experiment/nglite.yaml"',title:'"experiment/nglite.yaml"'},"# @package _global_\ndefaults:\n - override /db: sqlite\n - override /server: nginx\n \nserver:\n port: 8080\n")))),(0,i.mdx)("div",{className:"row"},(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py +experiment=aplite"',title:'"$',python:!0,"my_app.py":!0,"+experiment":'aplite"'},"db:\n name: sqlite\nserver:\n name: apache\n port: 8080\n"))),(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py +experiment=nglite"',title:'"$',python:!0,"my_app.py":!0,"+experiment":'nglite"'},"db:\n name: sqlite\nserver:\n name: nginx\n port: 8080\n")))),(0,i.mdx)("p",null,"Key concepts:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"#"," @package ","_","global","_"),(0,i.mdx)("br",{parentName:"li"}),"Changes specified in this config should be interpreted as relative to the ","_","global","_"," package.",(0,i.mdx)("br",{parentName:"li"}),"We could instead place ",(0,i.mdx)("em",{parentName:"li"},"nglite.yaml")," and ",(0,i.mdx)("em",{parentName:"li"},"aplite.yaml")," next to ",(0,i.mdx)("em",{parentName:"li"},"config.yaml")," and omit this line."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"The overrides of /db and /server are absolute paths."),(0,i.mdx)("br",{parentName:"li"}),"This is necessary because they are outside of the experiment directory. ")),(0,i.mdx)("p",null,"Running the experiments from the command line requires prefixing the experiment choice with a ",(0,i.mdx)("inlineCode",{parentName:"p"},"+"),".\nThe experiment config group is an addition, not an override."),(0,i.mdx)("h3",{id:"sweeping-over-experiments"},"Sweeping over experiments"),(0,i.mdx)("p",null,"This approach also enables sweeping over those experiments to easily compare their results:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="$ python my_app.py --multirun +experiment=aplite,nglite"',title:'"$',python:!0,"my_app.py":!0,"--multirun":!0,"+experiment":'aplite,nglite"'},"[HYDRA] Launching 2 jobs locally\n[HYDRA] #0 : +experiment=aplite\ndb:\n name: sqlite\nserver:\n name: apache\n port: 8080\n\n[HYDRA] #1 : +experiment=nglite\ndb:\n name: sqlite\nserver:\n name: nginx\n port: 8080\n")),(0,i.mdx)("p",null,"To run all the experiments, use the ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.2/advanced/override_grammar/extended#glob-choice-sweep"},"glob")," syntax:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text",metastring:"title=\"$ python my_app.py --multirun '+experiment=glob(*)'\"",title:'"$',python:!0,"my_app.py":!0,"--multirun":!0,"'+experiment":"glob(*)'\""},"[HYDRA] #0 : +experiment=aplite\n...\n[HYDRA] #1 : +experiment=nglite\n...\n")))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/0b3cc50a.a581d8dd.js b/assets/js/0b3cc50a.a581d8dd.js new file mode 100644 index 0000000000..2933203ff2 --- /dev/null +++ b/assets/js/0b3cc50a.a581d8dd.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[2838],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>m,MDXProvider:()=>c,mdx:()=>y,useMDXComponents:()=>s,withMDXComponents:()=>p});var r=a(96540);function t(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function l(){return l=Object.assign||function(e){for(var n=1;n=0||(t[a]=e[a]);return t}(e,n);if(Object.getOwnPropertySymbols){var l=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(t[a]=e[a])}return t}var m=r.createContext({}),p=function(e){return function(n){var a=s(n.components);return r.createElement(e,l({},n,{components:a}))}},s=function(e){var n=r.useContext(m),a=n;return e&&(a="function"==typeof e?e(n):o(o({},n),e)),a},c=function(e){var n=s(e.components);return r.createElement(m.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},h=r.forwardRef((function(e,n){var a=e.components,t=e.mdxType,l=e.originalType,i=e.parentName,m=d(e,["components","mdxType","originalType","parentName"]),p=s(a),c=t,h=p["".concat(i,".").concat(c)]||p[c]||u[c]||l;return a?r.createElement(h,o(o({ref:n},m),{},{components:a})):r.createElement(h,o({ref:n},m))}));function y(e,n){var a=arguments,t=n&&n.mdxType;if("string"==typeof e||t){var l=a.length,i=new Array(l);i[0]=h;var o={};for(var d in n)hasOwnProperty.call(n,d)&&(o[d]=n[d]);o.originalType=e,o.mdxType="string"==typeof e?e:t,i[1]=o;for(var m=2;m{a.d(n,{A:()=>d,C:()=>m});var r=a(58168),t=a(96540),l=a(75489),i=a(44586),o=a(74098);function d(e){return t.createElement(l.default,(0,r.A)({},e,{to:(n=e.to,d=(0,o.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(a=null==d?void 0:d.name)?a:"current"]+n),target:"_blank"}));var n,a,d}function m(e){var n,a=null!=(n=e.text)?n:"Example (Click Here)";return t.createElement(d,e,t.createElement("span",null,"\xa0"),t.createElement("img",{src:"https://img.shields.io/badge/-"+a+"-informational",alt:"Example (Click Here)"}))}},58476:(e,n,a)=>{a.r(n),a.d(n,{contentTitle:()=>m,default:()=>u,frontMatter:()=>d,metadata:()=>p,toc:()=>s});var r=a(58168),t=a(98587),l=(a(96540),a(15680)),i=a(49595),o=["components"],d={id:"ray_launcher",title:"Ray Launcher plugin",sidebar_label:"Ray Launcher plugin"},m=void 0,p={unversionedId:"plugins/ray_launcher",id:"version-1.3/plugins/ray_launcher",title:"Ray Launcher plugin",description:"PyPI",source:"@site/versioned_docs/version-1.3/plugins/ray_launcher.md",sourceDirName:"plugins",slug:"/plugins/ray_launcher",permalink:"/docs/1.3/plugins/ray_launcher",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/plugins/ray_launcher.md",tags:[],version:"1.3",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"ray_launcher",title:"Ray Launcher plugin",sidebar_label:"Ray Launcher plugin"},sidebar:"docs",previous:{title:"Joblib Launcher plugin",permalink:"/docs/1.3/plugins/joblib_launcher"},next:{title:"RQ Launcher plugin",permalink:"/docs/1.3/plugins/rq_launcher"}},s=[{value:"Installation",id:"installation",children:[],level:3},{value:"Usage",id:"usage",children:[],level:3},{value:"ray_aws launcher",id:"ray_aws-launcher",children:[{value:"Examples",id:"examples",children:[{value:"Manage Cluster LifeCycle",id:"manage-cluster-lifecycle",children:[],level:5},{value:"Configure Ray Logging",id:"configure-ray-logging",children:[],level:5}],level:4}],level:3},{value:"ray launcher",id:"ray-launcher",children:[],level:3},{value:"Configure ray.init() and ray.remote()",id:"configure-rayinit-and-rayremote",children:[],level:3}],c={toc:s};function u(e){var n=e.components,a=(0,t.A)(e,o);return(0,l.mdx)("wrapper",(0,r.A)({},c,a,{components:n,mdxType:"MDXLayout"}),(0,l.mdx)("p",null,(0,l.mdx)("a",{parentName:"p",href:"https://pypi.org/project/hydra-ray-launcher/"},(0,l.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/v/hydra-ray-launcher",alt:"PyPI"})),"\n",(0,l.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/l/hydra-ray-launcher",alt:"PyPI - License"}),"\n",(0,l.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/pyversions/hydra-ray-launcher",alt:"PyPI - Python Version"}),"\n",(0,l.mdx)("a",{parentName:"p",href:"https://pypistats.org/packages/hydra-ray-launcher"},(0,l.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/dm/hydra-ray-launcher.svg",alt:"PyPI - Downloads"})),(0,l.mdx)(i.C,{text:"Example application",to:"plugins/hydra_ray_launcher/examples",mdxType:"ExampleGithubLink"}),(0,l.mdx)(i.C,{text:"Plugin source",to:"plugins/hydra_ray_launcher",mdxType:"ExampleGithubLink"})),(0,l.mdx)("p",null,"The Ray Launcher plugin provides 2 launchers: ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray_aws")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray"),".\n",(0,l.mdx)("inlineCode",{parentName:"p"},"ray_aws")," launches jobs remotely on AWS and is built on top of ",(0,l.mdx)("a",{parentName:"p",href:"https://docs.ray.io/en/releases-1.3.0/cluster/sdk.html"},"ray autoscaler sdk"),". ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray")," launches jobs on your local machine or existing ray cluster. "),(0,l.mdx)("h3",{id:"installation"},"Installation"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ pip install hydra-ray-launcher --upgrade\n")),(0,l.mdx)("h3",{id:"usage"},"Usage"),(0,l.mdx)("p",null,"Once installed, add ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra/launcher=ray_aws")," or ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra/launcher=ray")," to your command line. Alternatively, override ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra/launcher")," in your config:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - override hydra/launcher: ray_aws\n")),(0,l.mdx)("p",null,"There are several standard approaches for configuring plugins. Check ",(0,l.mdx)("a",{parentName:"p",href:"/docs/1.3/patterns/configuring_plugins"},"this page")," for more information."),(0,l.mdx)("h3",{id:"ray_aws-launcher"},(0,l.mdx)("inlineCode",{parentName:"h3"},"ray_aws")," launcher"),(0,l.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,l.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,l.mdx)("h5",{parentName:"div"},(0,l.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,l.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,l.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,l.mdx)("div",{parentName:"div",className:"admonition-content"},(0,l.mdx)("p",{parentName:"div"},(0,l.mdx)("inlineCode",{parentName:"p"},"ray_aws")," launcher is built on top of ray's ",(0,l.mdx)("a",{parentName:"p",href:"https://docs.ray.io/en/releases-1.3.0/cluster/sdk.html"},"autoscaler sdk"),". To get started, you need to\n",(0,l.mdx)("a",{parentName:"p",href:"https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html"},"config your AWS credentials"),".\n",(0,l.mdx)("inlineCode",{parentName:"p"},"ray autoscaler sdk")," expects your AWS credentials have certain permissions for ",(0,l.mdx)("a",{parentName:"p",href:"https://aws.amazon.com/ec2"},(0,l.mdx)("inlineCode",{parentName:"a"},"EC2"))," and ",(0,l.mdx)("a",{parentName:"p",href:"https://aws.amazon.com/iam"},(0,l.mdx)("inlineCode",{parentName:"a"},"IAM")),". Read ",(0,l.mdx)("a",{parentName:"p",href:"https://github.com/ray-project/ray/issues/9327"},"this")," for more information."))),(0,l.mdx)("p",null,(0,l.mdx)("inlineCode",{parentName:"p"},"ray autoscaler sdk")," expects a configuration for the EC2 cluster; we've schematized the configs in ",(0,l.mdx)(i.A,{to:"plugins/hydra_ray_launcher/hydra_plugins/hydra_ray_launcher/_config.py",mdxType:"GithubLink"},"here")),(0,l.mdx)("details",null,(0,l.mdx)("summary",null,"Discover ray_aws launcher's config"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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\nenv_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\nray:\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 initial_workers: 0\n autoscaling_mode: default\n target_utilization_fraction: 0.8\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\nstop_cluster: true\nsync_up:\n source_dir: null\n target_dir: null\n include: []\n exclude: []\nsync_down:\n source_dir: null\n target_dir: null\n include: []\n exclude: []\nlogging:\n log_style: auto\n color_mode: auto\n verbosity: 0\ncreate_update_cluster:\n no_restart: false\n restart_only: false\n no_config_cache: false\nteardown_cluster:\n workers_only: false\n keep_min_workers: false\n"))),(0,l.mdx)("h4",{id:"examples"},"Examples"),(0,l.mdx)("p",null,"The following examples can be found ",(0,l.mdx)(i.A,{to:"plugins/hydra_ray_launcher/examples",mdxType:"GithubLink"},"here"),"."),(0,l.mdx)("details",null,(0,l.mdx)("summary",null,"Simple app"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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\nCluster: default\n...\nINFO 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)\nDestroying cluster. Confirm [y/N]: y [automatic, due to --yes]\n...\nNo nodes remaining.\n\n"))),(0,l.mdx)("details",null,(0,l.mdx)("summary",null,"Upload & Download from remote cluster"),(0,l.mdx)("p",null,"If your application is dependent on multiple modules, you can configure ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.sync_up")," to upload dependency modules to the remote cluster.\nYou can also configure ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.sync_down")," to download output from remote cluster if needed. This functionality is built on top of ",(0,l.mdx)("inlineCode",{parentName:"p"},"rsync"),", ",(0,l.mdx)("inlineCode",{parentName:"p"},"include")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"exclude")," is consistent with how it works in ",(0,l.mdx)("inlineCode",{parentName:"p"},"rsync"),"."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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\nCluster: default\n...\nINFO 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\nLoaded cached provider configuration\n...\n[HYDRA] Output: receiving file list ... done\n16-32-25/\n16-32-25/0/\n16-32-25/0/checkpoint/\n16-32-25/0/checkpoint/checkpoint_1.pt\n16-32-25/1/\n16-32-25/1/checkpoint/\n16-32-25/1/checkpoint/checkpoint_2.pt\n16-32-25/2/\n16-32-25/2/checkpoint/\n16-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)\nDestroying cluster. Confirm [y/N]: y [automatic, due to --yes]\n...\nNo nodes remaining.\n\n"))),(0,l.mdx)("h5",{id:"manage-cluster-lifecycle"},"Manage Cluster LifeCycle"),(0,l.mdx)("p",null,"You can manage the Ray EC2 cluster lifecycle by configuring the flags provided by the plugin:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Default setting (no need to specify on commandline): delete cluster after job finishes remotely:"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.stop_cluster=true\nhydra.launcher.ray.cluster.provider.cache_stopped_nodes=false\nhydra.launcher.teardown_cluster.workers_only=false\nhydra.launcher.teardown_cluster.keep_min_workers=false\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Keep cluster running after jobs finishes remotely"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.stop_cluster=false\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Power off EC2 instances and control node termination using ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.cluster.provider.cache_stopped_nodes"),"\nand ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.teardown_cluster.workers_only")),(0,l.mdx)("table",{parentName:"li"},(0,l.mdx)("thead",{parentName:"table"},(0,l.mdx)("tr",{parentName:"thead"},(0,l.mdx)("th",{parentName:"tr",align:null},"cache_stopped_nodes"),(0,l.mdx)("th",{parentName:"tr",align:null},"workers_only"),(0,l.mdx)("th",{parentName:"tr",align:null},"behavior"))),(0,l.mdx)("tbody",{parentName:"table"},(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"All nodes are terminated")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"Keeps head node running and terminates only worker node")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"Keeps both head node and worker node and stops both of them")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"Keeps both head node and worker node and stops only worker node"))))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Keep ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.cluster.min_workers")," worker nodes\nand delete the rest of the worker nodes"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.teardown_cluster.keep_min_workers=true\n")))),(0,l.mdx)("p",null,"Additionally, you can configure how to create or update the cluster:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Default config: run setup commands, restart Ray and use\nthe config cache if available"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.create_update_cluster.no_restart=false\nhydra.launcher.create_update_cluster.restart_only=false\nhydra.launcher.create_update_cluster.no_config_cache=false\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Skip restarting Ray services when updating the cluster config"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.create_update_cluster.no_restart=true\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Skip running setup commands and only restart Ray (cannot be used with\n",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.create_update_cluster.no_restart"),")"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.create_update_cluster.restart_only=true\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Fully resolve all environment settings from the cloud provider again"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.create_update_cluster.no_config_cache=true\n")))),(0,l.mdx)("h5",{id:"configure-ray-logging"},"Configure Ray Logging"),(0,l.mdx)("p",null,"You can manage Ray specific logging by configuring the flags provided by the plugin:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Default config: use minimal verbosity and automatically\ndetect whether to use pretty-print and color mode"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},'hydra.launcher.logging.log_style="auto"\nhydra.launcher.logging.color_mode="auto"\nhydra.launcher.logging.verbosity=0\n'))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Disable pretty-print"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},'hydra.launcher.logging.log_style="record"\n'))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Disable color mode"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},'hydra.launcher.logging.color_mode="false"\n'))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Increase Ray logging verbosity"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.logging.verbosity=3\n")))),(0,l.mdx)("h3",{id:"ray-launcher"},(0,l.mdx)("inlineCode",{parentName:"h3"},"ray")," launcher"),(0,l.mdx)("p",null,(0,l.mdx)("inlineCode",{parentName:"p"},"ray")," launcher lets you launch application on your ray cluster or local machine. You can easily config how your jobs are executed by changing ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray")," launcher's configuration here\n",(0,l.mdx)("inlineCode",{parentName:"p"},"~/hydra/plugins/hydra_ray_launcher/hydra_plugins/hydra_ray_launcher/conf/hydra/launcher/ray.yaml")),(0,l.mdx)("p",null," The ",(0,l.mdx)(i.A,{to:"plugins/hydra_ray_launcher/examples/simple",mdxType:"GithubLink"},"example application")," starts a new ray cluster."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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")),(0,l.mdx)("p",null,"You can run the example application on your existing ray cluster as well by overriding ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.init.address"),":"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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")),(0,l.mdx)("h3",{id:"configure-rayinit-and-rayremote"},"Configure ",(0,l.mdx)("inlineCode",{parentName:"h3"},"ray.init()")," and ",(0,l.mdx)("inlineCode",{parentName:"h3"},"ray.remote()")),(0,l.mdx)("p",null,"Ray launcher is built on top of ",(0,l.mdx)("a",{parentName:"p",href:"https://docs.ray.io/en/master/package-ref.html?highlight=ray.remote#ray-init"},(0,l.mdx)("inlineCode",{parentName:"a"},"ray.init()")),"\nand ",(0,l.mdx)("a",{parentName:"p",href:"https://docs.ray.io/en/master/package-ref.html?highlight=ray.remote#ray-remote"},(0,l.mdx)("inlineCode",{parentName:"a"},"ray.remote()")),".\nYou can configure ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray")," by overriding ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.init")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.remote"),".\nCheck out an ",(0,l.mdx)(i.A,{to:"plugins/hydra_ray_launcher/examples/simple/config.yaml",mdxType:"GithubLink"},"example config"),"."))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/0b3cc50a.b9faaa78.js b/assets/js/0b3cc50a.b9faaa78.js deleted file mode 100644 index 8209cc735e..0000000000 --- a/assets/js/0b3cc50a.b9faaa78.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[2838],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>m,MDXProvider:()=>c,mdx:()=>y,useMDXComponents:()=>s,withMDXComponents:()=>p});var r=a(96540);function t(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function l(){return l=Object.assign||function(e){for(var n=1;n=0||(t[a]=e[a]);return t}(e,n);if(Object.getOwnPropertySymbols){var l=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(t[a]=e[a])}return t}var m=r.createContext({}),p=function(e){return function(n){var a=s(n.components);return r.createElement(e,l({},n,{components:a}))}},s=function(e){var n=r.useContext(m),a=n;return e&&(a="function"==typeof e?e(n):o(o({},n),e)),a},c=function(e){var n=s(e.components);return r.createElement(m.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},h=r.forwardRef((function(e,n){var a=e.components,t=e.mdxType,l=e.originalType,i=e.parentName,m=d(e,["components","mdxType","originalType","parentName"]),p=s(a),c=t,h=p["".concat(i,".").concat(c)]||p[c]||u[c]||l;return a?r.createElement(h,o(o({ref:n},m),{},{components:a})):r.createElement(h,o({ref:n},m))}));function y(e,n){var a=arguments,t=n&&n.mdxType;if("string"==typeof e||t){var l=a.length,i=new Array(l);i[0]=h;var o={};for(var d in n)hasOwnProperty.call(n,d)&&(o[d]=n[d]);o.originalType=e,o.mdxType="string"==typeof e?e:t,i[1]=o;for(var m=2;m{a.d(n,{A:()=>d,C:()=>m});var r=a(58168),t=a(96540),l=a(75489),i=a(44586),o=a(74098);function d(e){return t.createElement(l.default,(0,r.A)({},e,{to:(n=e.to,d=(0,o.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(a=null==d?void 0:d.name)?a:"current"]+n),target:"_blank"}));var n,a,d}function m(e){var n,a=null!=(n=e.text)?n:"Example (Click Here)";return t.createElement(d,e,t.createElement("span",null,"\xa0"),t.createElement("img",{src:"https://img.shields.io/badge/-"+a+"-informational",alt:"Example (Click Here)"}))}},58476:(e,n,a)=>{a.r(n),a.d(n,{contentTitle:()=>m,default:()=>u,frontMatter:()=>d,metadata:()=>p,toc:()=>s});var r=a(58168),t=a(98587),l=(a(96540),a(15680)),i=a(49595),o=["components"],d={id:"ray_launcher",title:"Ray Launcher plugin",sidebar_label:"Ray Launcher plugin"},m=void 0,p={unversionedId:"plugins/ray_launcher",id:"version-1.3/plugins/ray_launcher",title:"Ray Launcher plugin",description:"PyPI",source:"@site/versioned_docs/version-1.3/plugins/ray_launcher.md",sourceDirName:"plugins",slug:"/plugins/ray_launcher",permalink:"/docs/1.3/plugins/ray_launcher",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/plugins/ray_launcher.md",tags:[],version:"1.3",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"ray_launcher",title:"Ray Launcher plugin",sidebar_label:"Ray Launcher plugin"},sidebar:"docs",previous:{title:"Joblib Launcher plugin",permalink:"/docs/1.3/plugins/joblib_launcher"},next:{title:"RQ Launcher plugin",permalink:"/docs/1.3/plugins/rq_launcher"}},s=[{value:"Installation",id:"installation",children:[],level:3},{value:"Usage",id:"usage",children:[],level:3},{value:"ray_aws launcher",id:"ray_aws-launcher",children:[{value:"Examples",id:"examples",children:[{value:"Manage Cluster LifeCycle",id:"manage-cluster-lifecycle",children:[],level:5},{value:"Configure Ray Logging",id:"configure-ray-logging",children:[],level:5}],level:4}],level:3},{value:"ray launcher",id:"ray-launcher",children:[],level:3},{value:"Configure ray.init() and ray.remote()",id:"configure-rayinit-and-rayremote",children:[],level:3}],c={toc:s};function u(e){var n=e.components,a=(0,t.A)(e,o);return(0,l.mdx)("wrapper",(0,r.A)({},c,a,{components:n,mdxType:"MDXLayout"}),(0,l.mdx)("p",null,(0,l.mdx)("a",{parentName:"p",href:"https://pypi.org/project/hydra-ray-launcher/"},(0,l.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/v/hydra-ray-launcher",alt:"PyPI"})),"\n",(0,l.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/l/hydra-ray-launcher",alt:"PyPI - License"}),"\n",(0,l.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/pyversions/hydra-ray-launcher",alt:"PyPI - Python Version"}),"\n",(0,l.mdx)("a",{parentName:"p",href:"https://pypistats.org/packages/hydra-ray-launcher"},(0,l.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/dm/hydra-ray-launcher.svg",alt:"PyPI - Downloads"})),(0,l.mdx)(i.C,{text:"Example application",to:"plugins/hydra_ray_launcher/examples",mdxType:"ExampleGithubLink"}),(0,l.mdx)(i.C,{text:"Plugin source",to:"plugins/hydra_ray_launcher",mdxType:"ExampleGithubLink"})),(0,l.mdx)("p",null,"The Ray Launcher plugin provides 2 launchers: ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray_aws")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray"),".\n",(0,l.mdx)("inlineCode",{parentName:"p"},"ray_aws")," launches jobs remotely on AWS and is built on top of ",(0,l.mdx)("a",{parentName:"p",href:"https://docs.ray.io/en/releases-1.3.0/cluster/sdk.html"},"ray autoscaler sdk"),". ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray")," launches jobs on your local machine or existing ray cluster. "),(0,l.mdx)("h3",{id:"installation"},"Installation"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ pip install hydra-ray-launcher --upgrade\n")),(0,l.mdx)("h3",{id:"usage"},"Usage"),(0,l.mdx)("p",null,"Once installed, add ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra/launcher=ray_aws")," or ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra/launcher=ray")," to your command line. Alternatively, override ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra/launcher")," in your config:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - override hydra/launcher: ray_aws\n")),(0,l.mdx)("p",null,"There are several standard approaches for configuring plugins. Check ",(0,l.mdx)("a",{parentName:"p",href:"/docs/1.3/patterns/configuring_plugins"},"this page")," for more information."),(0,l.mdx)("h3",{id:"ray_aws-launcher"},(0,l.mdx)("inlineCode",{parentName:"h3"},"ray_aws")," launcher"),(0,l.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,l.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,l.mdx)("h5",{parentName:"div"},(0,l.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,l.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,l.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,l.mdx)("div",{parentName:"div",className:"admonition-content"},(0,l.mdx)("p",{parentName:"div"},(0,l.mdx)("inlineCode",{parentName:"p"},"ray_aws")," launcher is built on top of ray's ",(0,l.mdx)("a",{parentName:"p",href:"https://docs.ray.io/en/releases-1.3.0/cluster/sdk.html"},"autoscaler sdk"),". To get started, you need to\n",(0,l.mdx)("a",{parentName:"p",href:"https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html"},"config your AWS credentials"),".\n",(0,l.mdx)("inlineCode",{parentName:"p"},"ray autoscaler sdk")," expects your AWS credentials have certain permissions for ",(0,l.mdx)("a",{parentName:"p",href:"https://aws.amazon.com/ec2"},(0,l.mdx)("inlineCode",{parentName:"a"},"EC2"))," and ",(0,l.mdx)("a",{parentName:"p",href:"https://aws.amazon.com/iam"},(0,l.mdx)("inlineCode",{parentName:"a"},"IAM")),". Read ",(0,l.mdx)("a",{parentName:"p",href:"https://github.com/ray-project/ray/issues/9327"},"this")," for more information."))),(0,l.mdx)("p",null,(0,l.mdx)("inlineCode",{parentName:"p"},"ray autoscaler sdk")," expects a configuration for the EC2 cluster; we've schematized the configs in ",(0,l.mdx)(i.A,{to:"plugins/hydra_ray_launcher/hydra_plugins/hydra_ray_launcher/_config.py",mdxType:"GithubLink"},"here")),(0,l.mdx)("details",null,(0,l.mdx)("summary",null,"Discover ray_aws launcher's config"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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\nenv_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\nray:\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 initial_workers: 0\n autoscaling_mode: default\n target_utilization_fraction: 0.8\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\nstop_cluster: true\nsync_up:\n source_dir: null\n target_dir: null\n include: []\n exclude: []\nsync_down:\n source_dir: null\n target_dir: null\n include: []\n exclude: []\nlogging:\n log_style: auto\n color_mode: auto\n verbosity: 0\ncreate_update_cluster:\n no_restart: false\n restart_only: false\n no_config_cache: false\nteardown_cluster:\n workers_only: false\n keep_min_workers: false\n"))),(0,l.mdx)("h4",{id:"examples"},"Examples"),(0,l.mdx)("p",null,"The following examples can be found ",(0,l.mdx)(i.A,{to:"plugins/hydra_ray_launcher/examples",mdxType:"GithubLink"},"here"),"."),(0,l.mdx)("details",null,(0,l.mdx)("summary",null,"Simple app"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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\nCluster: default\n...\nINFO 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)\nDestroying cluster. Confirm [y/N]: y [automatic, due to --yes]\n...\nNo nodes remaining.\n\n"))),(0,l.mdx)("details",null,(0,l.mdx)("summary",null,"Upload & Download from remote cluster"),(0,l.mdx)("p",null,"If your application is dependent on multiple modules, you can configure ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.sync_up")," to upload dependency modules to the remote cluster.\nYou can also configure ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.sync_down")," to download output from remote cluster if needed. This functionality is built on top of ",(0,l.mdx)("inlineCode",{parentName:"p"},"rsync"),", ",(0,l.mdx)("inlineCode",{parentName:"p"},"include")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"exclude")," is consistent with how it works in ",(0,l.mdx)("inlineCode",{parentName:"p"},"rsync"),"."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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\nCluster: default\n...\nINFO 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\nLoaded cached provider configuration\n...\n[HYDRA] Output: receiving file list ... done\n16-32-25/\n16-32-25/0/\n16-32-25/0/checkpoint/\n16-32-25/0/checkpoint/checkpoint_1.pt\n16-32-25/1/\n16-32-25/1/checkpoint/\n16-32-25/1/checkpoint/checkpoint_2.pt\n16-32-25/2/\n16-32-25/2/checkpoint/\n16-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)\nDestroying cluster. Confirm [y/N]: y [automatic, due to --yes]\n...\nNo nodes remaining.\n\n"))),(0,l.mdx)("h5",{id:"manage-cluster-lifecycle"},"Manage Cluster LifeCycle"),(0,l.mdx)("p",null,"You can manage the Ray EC2 cluster lifecycle by configuring the flags provided by the plugin:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Default setting (no need to specify on commandline): delete cluster after job finishes remotely:"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.stop_cluster=true\nhydra.launcher.ray.cluster.provider.cache_stopped_nodes=false\nhydra.launcher.teardown_cluster.workers_only=false\nhydra.launcher.teardown_cluster.keep_min_workers=false\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Keep cluster running after jobs finishes remotely"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.stop_cluster=false\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Power off EC2 instances and control node termination using ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.cluster.provider.cache_stopped_nodes"),"\nand ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.teardown_cluster.workers_only")),(0,l.mdx)("table",{parentName:"li"},(0,l.mdx)("thead",{parentName:"table"},(0,l.mdx)("tr",{parentName:"thead"},(0,l.mdx)("th",{parentName:"tr",align:null},"cache_stopped_nodes"),(0,l.mdx)("th",{parentName:"tr",align:null},"workers_only"),(0,l.mdx)("th",{parentName:"tr",align:null},"behavior"))),(0,l.mdx)("tbody",{parentName:"table"},(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"All nodes are terminated")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"Keeps head node running and terminates only worker node")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"Keeps both head node and worker node and stops both of them")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"Keeps both head node and worker node and stops only worker node"))))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Keep ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.cluster.min_workers")," worker nodes\nand delete the rest of the worker nodes"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.teardown_cluster.keep_min_workers=true\n")))),(0,l.mdx)("p",null,"Additionally, you can configure how to create or update the cluster:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Default config: run setup commands, restart Ray and use\nthe config cache if available"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.create_update_cluster.no_restart=false\nhydra.launcher.create_update_cluster.restart_only=false\nhydra.launcher.create_update_cluster.no_config_cache=false\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Skip restarting Ray services when updating the cluster config"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.create_update_cluster.no_restart=true\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Skip running setup commands and only restart Ray (cannot be used with\n",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.create_update_cluster.no_restart"),")"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.create_update_cluster.restart_only=true\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Fully resolve all environment settings from the cloud provider again"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.create_update_cluster.no_config_cache=true\n")))),(0,l.mdx)("h5",{id:"configure-ray-logging"},"Configure Ray Logging"),(0,l.mdx)("p",null,"You can manage Ray specific logging by configuring the flags provided by the plugin:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Default config: use minimal verbosity and automatically\ndetect whether to use pretty-print and color mode"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},'hydra.launcher.logging.log_style="auto"\nhydra.launcher.logging.color_mode="auto"\nhydra.launcher.logging.verbosity=0\n'))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Disable pretty-print"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},'hydra.launcher.logging.log_style="record"\n'))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Disable color mode"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},'hydra.launcher.logging.color_mode="false"\n'))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Increase Ray logging verbosity"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.logging.verbosity=3\n")))),(0,l.mdx)("h3",{id:"ray-launcher"},(0,l.mdx)("inlineCode",{parentName:"h3"},"ray")," launcher"),(0,l.mdx)("p",null,(0,l.mdx)("inlineCode",{parentName:"p"},"ray")," launcher lets you launch application on your ray cluster or local machine. You can easily config how your jobs are executed by changing ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray")," launcher's configuration here\n",(0,l.mdx)("inlineCode",{parentName:"p"},"~/hydra/plugins/hydra_ray_launcher/hydra_plugins/hydra_ray_launcher/conf/hydra/launcher/ray.yaml")),(0,l.mdx)("p",null," The ",(0,l.mdx)(i.A,{to:"plugins/hydra_ray_launcher/examples/simple",mdxType:"GithubLink"},"example application")," starts a new ray cluster."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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")),(0,l.mdx)("p",null,"You can run the example application on your existing ray cluster as well by overriding ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.init.address"),":"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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")),(0,l.mdx)("h3",{id:"configure-rayinit-and-rayremote"},"Configure ",(0,l.mdx)("inlineCode",{parentName:"h3"},"ray.init()")," and ",(0,l.mdx)("inlineCode",{parentName:"h3"},"ray.remote()")),(0,l.mdx)("p",null,"Ray launcher is built on top of ",(0,l.mdx)("a",{parentName:"p",href:"https://docs.ray.io/en/master/package-ref.html?highlight=ray.remote#ray-init"},(0,l.mdx)("inlineCode",{parentName:"a"},"ray.init()")),"\nand ",(0,l.mdx)("a",{parentName:"p",href:"https://docs.ray.io/en/master/package-ref.html?highlight=ray.remote#ray-remote"},(0,l.mdx)("inlineCode",{parentName:"a"},"ray.remote()")),".\nYou can configure ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray")," by overriding ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.init")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.remote"),".\nCheck out an ",(0,l.mdx)(i.A,{to:"plugins/hydra_ray_launcher/examples/simple/config.yaml",mdxType:"GithubLink"},"example config"),"."))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/0e384e19.27320c87.js b/assets/js/0e384e19.27320c87.js new file mode 100644 index 0000000000..24fecdae23 --- /dev/null +++ b/assets/js/0e384e19.27320c87.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3976],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>d,MDXProvider:()=>u,mdx:()=>h,useMDXComponents:()=>p,withMDXComponents:()=>s});var a=n(96540);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var d=a.createContext({}),s=function(e){return function(t){var n=p(t.components);return a.createElement(e,o({},t,{components:n}))}},p=function(e){var t=a.useContext(d),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},u=function(e){var t=p(e.components);return a.createElement(d.Provider,{value:t},e.children)},c={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},f=a.forwardRef((function(e,t){var n=e.components,r=e.mdxType,o=e.originalType,l=e.parentName,d=m(e,["components","mdxType","originalType","parentName"]),s=p(n),u=r,f=s["".concat(l,".").concat(u)]||s[u]||c[u]||o;return n?a.createElement(f,i(i({ref:t},d),{},{components:n})):a.createElement(f,i({ref:t},d))}));function h(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var o=n.length,l=new Array(o);l[0]=f;var i={};for(var m in t)hasOwnProperty.call(t,m)&&(i[m]=t[m]);i.originalType=e,i.mdxType="string"==typeof e?e:r,l[1]=i;for(var d=2;d{n.r(t),n.d(t,{contentTitle:()=>m,default:()=>u,frontMatter:()=>i,metadata:()=>d,toc:()=>s});var a=n(58168),r=n(98587),o=(n(96540),n(15680)),l=(n(86025),n(75489),["components"]),i={id:"intro",title:"Getting started",sidebar_label:"Getting started"},m=void 0,d={unversionedId:"intro",id:"intro",title:"Getting started",description:"Introduction",source:"@site/docs/intro.md",sourceDirName:".",slug:"/intro",permalink:"/docs/intro",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/intro.md",tags:[],version:"current",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"intro",title:"Getting started",sidebar_label:"Getting started"},sidebar:"docs",next:{title:"Tutorials intro",permalink:"/docs/tutorials/intro"}},s=[{value:"Introduction",id:"introduction",children:[{value:"Key features:",id:"key-features",children:[],level:3}],level:2},{value:"Versions",id:"versions",children:[],level:2},{value:"Quick start guide",id:"quick-start-guide",children:[{value:"Installation",id:"installation",children:[],level:3},{value:"Basic example",id:"basic-example",children:[],level:3},{value:"Composition example",id:"composition-example",children:[],level:3},{value:"Multirun",id:"multirun",children:[],level:3}],level:2},{value:"Other stuff",id:"other-stuff",children:[{value:"Community",id:"community",children:[],level:3},{value:"Citing Hydra",id:"citing-hydra",children:[],level:3}],level:2}],p={toc:s};function u(e){var t=e.components,n=(0,r.A)(e,l);return(0,o.mdx)("wrapper",(0,a.A)({},p,n,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)("h2",{id:"introduction"},"Introduction"),(0,o.mdx)("p",null,"Hydra is an open-source Python framework that simplifies the development of research and other complex applications.\nThe key feature is the ability to dynamically create a hierarchical configuration by composition and override it through config files and the command line.\nThe name Hydra comes from its ability to run multiple similar jobs - much like a Hydra with multiple heads."),(0,o.mdx)("h3",{id:"key-features"},"Key features:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"Hierarchical configuration composable from multiple sources"),(0,o.mdx)("li",{parentName:"ul"},"Configuration can be specified or overridden from the command line"),(0,o.mdx)("li",{parentName:"ul"},"Dynamic command line tab completion"),(0,o.mdx)("li",{parentName:"ul"},"Run your application locally or launch it to run remotely"),(0,o.mdx)("li",{parentName:"ul"},"Run multiple jobs with different arguments with a single command")),(0,o.mdx)("h2",{id:"versions"},"Versions"),(0,o.mdx)("p",null,"Hydra supports Linux, Mac and Windows.",(0,o.mdx)("br",{parentName:"p"}),"\n","Use the version switcher in the top bar to switch between documentation versions."),(0,o.mdx)("table",null,(0,o.mdx)("thead",{parentName:"table"},(0,o.mdx)("tr",{parentName:"thead"},(0,o.mdx)("th",{parentName:"tr",align:null}),(0,o.mdx)("th",{parentName:"tr",align:null},"Version"),(0,o.mdx)("th",{parentName:"tr",align:null},"Release notes"),(0,o.mdx)("th",{parentName:"tr",align:null},"Python Versions"))),(0,o.mdx)("tbody",{parentName:"table"},(0,o.mdx)("tr",{parentName:"tbody"},(0,o.mdx)("td",{parentName:"tr",align:null},"\u25ba"),(0,o.mdx)("td",{parentName:"tr",align:null},"1.3 (Stable)"),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v1.3.0"},"Release notes")),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("strong",{parentName:"td"},"3.6 - 3.11"))),(0,o.mdx)("tr",{parentName:"tbody"},(0,o.mdx)("td",{parentName:"tr",align:null}),(0,o.mdx)("td",{parentName:"tr",align:null},"1.2"),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v1.2.0"},"Release notes")),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("strong",{parentName:"td"},"3.6 - 3.10"))),(0,o.mdx)("tr",{parentName:"tbody"},(0,o.mdx)("td",{parentName:"tr",align:null}),(0,o.mdx)("td",{parentName:"tr",align:null},"1.1"),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v1.1.1"},"Release notes")),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("strong",{parentName:"td"},"3.6 - 3.9"))),(0,o.mdx)("tr",{parentName:"tbody"},(0,o.mdx)("td",{parentName:"tr",align:null}),(0,o.mdx)("td",{parentName:"tr",align:null},"1.0"),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v1.0.7"},"Release notes")),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("strong",{parentName:"td"},"3.6 - 3.8"))),(0,o.mdx)("tr",{parentName:"tbody"},(0,o.mdx)("td",{parentName:"tr",align:null}),(0,o.mdx)("td",{parentName:"tr",align:null},"0.11"),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v0.11.3"},"Release notes")),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("strong",{parentName:"td"},"2.7, 3.5 - 3.8"))))),(0,o.mdx)("h2",{id:"quick-start-guide"},"Quick start guide"),(0,o.mdx)("p",null,"This guide will show you some of the most important features you get by writing your application as a Hydra app.\nIf you only want to use Hydra for config composition, check out Hydra's ",(0,o.mdx)("a",{parentName:"p",href:"/docs/advanced/compose_api"},"compose API")," for an alternative.\nPlease also read the full ",(0,o.mdx)("a",{parentName:"p",href:"/docs/tutorials/basic/your_first_app/simple_cli"},"tutorial")," to gain a deeper understanding."),(0,o.mdx)("h3",{id:"installation"},"Installation"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-commandline"},"pip install hydra-core --upgrade\n")),(0,o.mdx)("h3",{id:"basic-example"},"Basic example"),(0,o.mdx)("p",null,"Config:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="conf/config.yaml"',title:'"conf/config.yaml"'},"db:\n driver: mysql\n user: omry\n pass: secret\n")),(0,o.mdx)("p",null,"Application:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'{4-6} title="my_app.py"',"{4-6}":!0,title:'"my_app.py"'},'import hydra\nfrom omegaconf import DictConfig, OmegaConf\n\n@hydra.main(version_base=None, config_path="conf", config_name="config")\ndef my_app(cfg : DictConfig) -> None:\n print(OmegaConf.to_yaml(cfg))\n\nif __name__ == "__main__":\n my_app()\n')),(0,o.mdx)("p",null,"You can learn more about OmegaConf ",(0,o.mdx)("a",{parentName:"p",href:"https://omegaconf.readthedocs.io/en/latest/usage.html#access-and-manipulation"},"here")," later."),(0,o.mdx)("p",null,(0,o.mdx)("inlineCode",{parentName:"p"},"config.yaml")," is loaded automatically when you run your application"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py\ndb:\n driver: mysql\n pass: secret\n user: omry\n")),(0,o.mdx)("p",null,"You can override values in the loaded config from the command line:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{4-5}","{4-5}":!0},"$ python my_app.py db.user=root db.pass=1234\ndb:\n driver: mysql\n user: root\n pass: 1234\n")),(0,o.mdx)("h3",{id:"composition-example"},"Composition example"),(0,o.mdx)("p",null,"You may want to alternate between two different databases. To support this create a ",(0,o.mdx)("inlineCode",{parentName:"p"},"config group")," named db,\nand place one config file for each alternative inside:\nThe directory structure of our application now looks like:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-text"},"\u251c\u2500\u2500 conf\n\u2502\xa0\xa0 \u251c\u2500\u2500 config.yaml\n\u2502\xa0\xa0 \u251c\u2500\u2500 db\n\u2502\xa0\xa0 \u2502\xa0\xa0 \u251c\u2500\u2500 mysql.yaml\n\u2502\xa0\xa0 \u2502\xa0\xa0 \u2514\u2500\u2500 postgresql.yaml\n\u2502\xa0\xa0 \u2514\u2500\u2500 __init__.py\n\u2514\u2500\u2500 my_app.py\n")),(0,o.mdx)("p",null,"Here is the new config:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="conf/config.yaml"',title:'"conf/config.yaml"'},"defaults:\n - db: mysql\n")),(0,o.mdx)("p",null,(0,o.mdx)("inlineCode",{parentName:"p"},"defaults")," is a special directive telling Hydra to use db/mysql.yaml when composing the configuration object.\nThe resulting cfg object is a composition of configs from defaults with configs specified in your ",(0,o.mdx)("inlineCode",{parentName:"p"},"config.yaml"),"."),(0,o.mdx)("p",null,"You can now choose which database configuration to use and override values from the command line: "),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py db=postgresql db.timeout=20\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 20\n user: postgres_user\n")),(0,o.mdx)("p",null,"You can have as many config groups as you need."),(0,o.mdx)("h3",{id:"multirun"},"Multirun"),(0,o.mdx)("p",null,"You can run your function multiple times with different configurations easily with the ",(0,o.mdx)("inlineCode",{parentName:"p"},"--multirun|-m")," flag."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre"},"$ python my_app.py --multirun db=mysql,postgresql\n[HYDRA] Sweep output dir : multirun/2020-01-09/01-16-29\n[HYDRA] Launching 2 jobs locally\n[HYDRA] #0 : db=mysql\ndb:\n driver: mysql\n pass: secret\n user: omry\n\n[HYDRA] #1 : db=postgresql\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 10\n user: postgres_user\n")),(0,o.mdx)("p",null,"There is a whole lot more to Hydra. Read the ",(0,o.mdx)("a",{parentName:"p",href:"/docs/tutorials/basic/your_first_app/simple_cli"},"tutorial")," to learn more."),(0,o.mdx)("h2",{id:"other-stuff"},"Other stuff"),(0,o.mdx)("h3",{id:"community"},"Community"),(0,o.mdx)("p",null,"Ask questions on github or StackOverflow (Use the tag #fb-hydra):"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("a",{parentName:"li",href:"https://github.com/facebookresearch/hydra/discussions"},"github")),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("a",{parentName:"li",href:"https://stackoverflow.com/questions/tagged/fb-hydra"},"StackOverflow"))),(0,o.mdx)("p",null,"Follow Hydra on Twitter and Facebook:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("a",{parentName:"li",href:"https://www.facebook.com/Hydra-Framework-109364473802509/"},"Facebook page")),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("a",{parentName:"li",href:"https://twitter.com/Hydra_Framework"},"Twitter"))),(0,o.mdx)("h3",{id:"citing-hydra"},"Citing Hydra"),(0,o.mdx)("p",null,"If you use Hydra in your research please use the following BibTeX entry:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-text"},"@Misc{Yadan2019Hydra,\n author = {Omry Yadan},\n title = {Hydra - A framework for elegantly configuring complex applications},\n howpublished = {Github},\n year = {2019},\n url = {https://github.com/facebookresearch/hydra}\n}\n")))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/0e384e19.9079822e.js b/assets/js/0e384e19.9079822e.js deleted file mode 100644 index b4123dab9c..0000000000 --- a/assets/js/0e384e19.9079822e.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3976],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>d,MDXProvider:()=>u,mdx:()=>h,useMDXComponents:()=>p,withMDXComponents:()=>s});var a=n(96540);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function l(){return l=Object.assign||function(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var l=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var d=a.createContext({}),s=function(e){return function(t){var n=p(t.components);return a.createElement(e,l({},t,{components:n}))}},p=function(e){var t=a.useContext(d),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},u=function(e){var t=p(e.components);return a.createElement(d.Provider,{value:t},e.children)},c={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},f=a.forwardRef((function(e,t){var n=e.components,r=e.mdxType,l=e.originalType,o=e.parentName,d=m(e,["components","mdxType","originalType","parentName"]),s=p(n),u=r,f=s["".concat(o,".").concat(u)]||s[u]||c[u]||l;return n?a.createElement(f,i(i({ref:t},d),{},{components:n})):a.createElement(f,i({ref:t},d))}));function h(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var l=n.length,o=new Array(l);o[0]=f;var i={};for(var m in t)hasOwnProperty.call(t,m)&&(i[m]=t[m]);i.originalType=e,i.mdxType="string"==typeof e?e:r,o[1]=i;for(var d=2;d{n.r(t),n.d(t,{contentTitle:()=>m,default:()=>u,frontMatter:()=>i,metadata:()=>d,toc:()=>s});var a=n(58168),r=n(98587),l=(n(96540),n(15680)),o=(n(86025),n(75489),["components"]),i={id:"intro",title:"Getting started",sidebar_label:"Getting started"},m=void 0,d={unversionedId:"intro",id:"intro",title:"Getting started",description:"Introduction",source:"@site/docs/intro.md",sourceDirName:".",slug:"/intro",permalink:"/docs/intro",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/intro.md",tags:[],version:"current",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"intro",title:"Getting started",sidebar_label:"Getting started"},sidebar:"docs",next:{title:"Tutorials intro",permalink:"/docs/tutorials/intro"}},s=[{value:"Introduction",id:"introduction",children:[{value:"Key features:",id:"key-features",children:[],level:3}],level:2},{value:"Versions",id:"versions",children:[],level:2},{value:"Quick start guide",id:"quick-start-guide",children:[{value:"Installation",id:"installation",children:[],level:3},{value:"Basic example",id:"basic-example",children:[],level:3},{value:"Composition example",id:"composition-example",children:[],level:3},{value:"Multirun",id:"multirun",children:[],level:3}],level:2},{value:"Other stuff",id:"other-stuff",children:[{value:"Community",id:"community",children:[],level:3},{value:"Citing Hydra",id:"citing-hydra",children:[],level:3}],level:2}],p={toc:s};function u(e){var t=e.components,n=(0,r.A)(e,o);return(0,l.mdx)("wrapper",(0,a.A)({},p,n,{components:t,mdxType:"MDXLayout"}),(0,l.mdx)("h2",{id:"introduction"},"Introduction"),(0,l.mdx)("p",null,"Hydra is an open-source Python framework that simplifies the development of research and other complex applications.\nThe key feature is the ability to dynamically create a hierarchical configuration by composition and override it through config files and the command line.\nThe name Hydra comes from its ability to run multiple similar jobs - much like a Hydra with multiple heads."),(0,l.mdx)("h3",{id:"key-features"},"Key features:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},"Hierarchical configuration composable from multiple sources"),(0,l.mdx)("li",{parentName:"ul"},"Configuration can be specified or overridden from the command line"),(0,l.mdx)("li",{parentName:"ul"},"Dynamic command line tab completion"),(0,l.mdx)("li",{parentName:"ul"},"Run your application locally or launch it to run remotely"),(0,l.mdx)("li",{parentName:"ul"},"Run multiple jobs with different arguments with a single command")),(0,l.mdx)("h2",{id:"versions"},"Versions"),(0,l.mdx)("p",null,"Hydra supports Linux, Mac and Windows.",(0,l.mdx)("br",{parentName:"p"}),"\n","Use the version switcher in the top bar to switch between documentation versions."),(0,l.mdx)("table",null,(0,l.mdx)("thead",{parentName:"table"},(0,l.mdx)("tr",{parentName:"thead"},(0,l.mdx)("th",{parentName:"tr",align:null}),(0,l.mdx)("th",{parentName:"tr",align:null},"Version"),(0,l.mdx)("th",{parentName:"tr",align:null},"Release notes"),(0,l.mdx)("th",{parentName:"tr",align:null},"Python Versions"))),(0,l.mdx)("tbody",{parentName:"table"},(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u25ba"),(0,l.mdx)("td",{parentName:"tr",align:null},"1.3 (Stable)"),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v1.3.0"},"Release notes")),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("strong",{parentName:"td"},"3.6 - 3.11"))),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null}),(0,l.mdx)("td",{parentName:"tr",align:null},"1.2"),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v1.2.0"},"Release notes")),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("strong",{parentName:"td"},"3.6 - 3.10"))),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null}),(0,l.mdx)("td",{parentName:"tr",align:null},"1.1"),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v1.1.1"},"Release notes")),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("strong",{parentName:"td"},"3.6 - 3.9"))),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null}),(0,l.mdx)("td",{parentName:"tr",align:null},"1.0"),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v1.0.7"},"Release notes")),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("strong",{parentName:"td"},"3.6 - 3.8"))),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null}),(0,l.mdx)("td",{parentName:"tr",align:null},"0.11"),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v0.11.3"},"Release notes")),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("strong",{parentName:"td"},"2.7, 3.5 - 3.8"))))),(0,l.mdx)("h2",{id:"quick-start-guide"},"Quick start guide"),(0,l.mdx)("p",null,"This guide will show you some of the most important features you get by writing your application as a Hydra app.\nIf you only want to use Hydra for config composition, check out Hydra's ",(0,l.mdx)("a",{parentName:"p",href:"/docs/advanced/compose_api"},"compose API")," for an alternative.\nPlease also read the full ",(0,l.mdx)("a",{parentName:"p",href:"/docs/tutorials/basic/your_first_app/simple_cli"},"tutorial")," to gain a deeper understanding."),(0,l.mdx)("h3",{id:"installation"},"Installation"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"pip install hydra-core --upgrade\n")),(0,l.mdx)("h3",{id:"basic-example"},"Basic example"),(0,l.mdx)("p",null,"Config:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="conf/config.yaml"',title:'"conf/config.yaml"'},"db:\n driver: mysql\n user: omry\n pass: secret\n")),(0,l.mdx)("p",null,"Application:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'{4-6} title="my_app.py"',"{4-6}":!0,title:'"my_app.py"'},'import hydra\nfrom omegaconf import DictConfig, OmegaConf\n\n@hydra.main(version_base=None, config_path="conf", config_name="config")\ndef my_app(cfg : DictConfig) -> None:\n print(OmegaConf.to_yaml(cfg))\n\nif __name__ == "__main__":\n my_app()\n')),(0,l.mdx)("p",null,"You can learn more about OmegaConf ",(0,l.mdx)("a",{parentName:"p",href:"https://omegaconf.readthedocs.io/en/latest/usage.html#access-and-manipulation"},"here")," later."),(0,l.mdx)("p",null,(0,l.mdx)("inlineCode",{parentName:"p"},"config.yaml")," is loaded automatically when you run your application"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py\ndb:\n driver: mysql\n pass: secret\n user: omry\n")),(0,l.mdx)("p",null,"You can override values in the loaded config from the command line:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{4-5}","{4-5}":!0},"$ python my_app.py db.user=root db.pass=1234\ndb:\n driver: mysql\n user: root\n pass: 1234\n")),(0,l.mdx)("h3",{id:"composition-example"},"Composition example"),(0,l.mdx)("p",null,"You may want to alternate between two different databases. To support this create a ",(0,l.mdx)("inlineCode",{parentName:"p"},"config group")," named db,\nand place one config file for each alternative inside:\nThe directory structure of our application now looks like:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-text"},"\u251c\u2500\u2500 conf\n\u2502\xa0\xa0 \u251c\u2500\u2500 config.yaml\n\u2502\xa0\xa0 \u251c\u2500\u2500 db\n\u2502\xa0\xa0 \u2502\xa0\xa0 \u251c\u2500\u2500 mysql.yaml\n\u2502\xa0\xa0 \u2502\xa0\xa0 \u2514\u2500\u2500 postgresql.yaml\n\u2502\xa0\xa0 \u2514\u2500\u2500 __init__.py\n\u2514\u2500\u2500 my_app.py\n")),(0,l.mdx)("p",null,"Here is the new config:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="conf/config.yaml"',title:'"conf/config.yaml"'},"defaults:\n - db: mysql\n")),(0,l.mdx)("p",null,(0,l.mdx)("inlineCode",{parentName:"p"},"defaults")," is a special directive telling Hydra to use db/mysql.yaml when composing the configuration object.\nThe resulting cfg object is a composition of configs from defaults with configs specified in your ",(0,l.mdx)("inlineCode",{parentName:"p"},"config.yaml"),"."),(0,l.mdx)("p",null,"You can now choose which database configuration to use and override values from the command line: "),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py db=postgresql db.timeout=20\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 20\n user: postgres_user\n")),(0,l.mdx)("p",null,"You can have as many config groups as you need."),(0,l.mdx)("h3",{id:"multirun"},"Multirun"),(0,l.mdx)("p",null,"You can run your function multiple times with different configurations easily with the ",(0,l.mdx)("inlineCode",{parentName:"p"},"--multirun|-m")," flag."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre"},"$ python my_app.py --multirun db=mysql,postgresql\n[HYDRA] Sweep output dir : multirun/2020-01-09/01-16-29\n[HYDRA] Launching 2 jobs locally\n[HYDRA] #0 : db=mysql\ndb:\n driver: mysql\n pass: secret\n user: omry\n\n[HYDRA] #1 : db=postgresql\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 10\n user: postgres_user\n")),(0,l.mdx)("p",null,"There is a whole lot more to Hydra. Read the ",(0,l.mdx)("a",{parentName:"p",href:"/docs/tutorials/basic/your_first_app/simple_cli"},"tutorial")," to learn more."),(0,l.mdx)("h2",{id:"other-stuff"},"Other stuff"),(0,l.mdx)("h3",{id:"community"},"Community"),(0,l.mdx)("p",null,"Ask questions on github or StackOverflow (Use the tag #fb-hydra):"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("a",{parentName:"li",href:"https://github.com/facebookresearch/hydra/discussions"},"github")),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("a",{parentName:"li",href:"https://stackoverflow.com/questions/tagged/fb-hydra"},"StackOverflow"))),(0,l.mdx)("p",null,"Follow Hydra on Twitter and Facebook:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("a",{parentName:"li",href:"https://www.facebook.com/Hydra-Framework-109364473802509/"},"Facebook page")),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("a",{parentName:"li",href:"https://twitter.com/Hydra_Framework"},"Twitter"))),(0,l.mdx)("h3",{id:"citing-hydra"},"Citing Hydra"),(0,l.mdx)("p",null,"If you use Hydra in your research please use the following BibTeX entry:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-text"},"@Misc{Yadan2019Hydra,\n author = {Omry Yadan},\n title = {Hydra - A framework for elegantly configuring complex applications},\n howpublished = {Github},\n year = {2019},\n url = {https://github.com/facebookresearch/hydra}\n}\n")))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/0e5950c6.0fe97605.js b/assets/js/0e5950c6.0fe97605.js new file mode 100644 index 0000000000..28f5dbb7ec --- /dev/null +++ b/assets/js/0e5950c6.0fe97605.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[7060],{15680:(e,r,t)=>{t.r(r),t.d(r,{MDXContext:()=>s,MDXProvider:()=>l,mdx:()=>m,useMDXComponents:()=>u,withMDXComponents:()=>p});var n=t(96540);function o(e,r,t){return r in e?Object.defineProperty(e,r,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[r]=t,e}function i(){return i=Object.assign||function(e){for(var r=1;r=0||(o[t]=e[t]);return o}(e,r);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(o[t]=e[t])}return o}var s=n.createContext({}),p=function(e){return function(r){var t=u(r.components);return n.createElement(e,i({},r,{components:t}))}},u=function(e){var r=n.useContext(s),t=r;return e&&(t="function"==typeof e?e(r):d(d({},r),e)),t},l=function(e){var r=u(e.components);return n.createElement(s.Provider,{value:r},e.children)},h={inlineCode:"code",wrapper:function(e){var r=e.children;return n.createElement(n.Fragment,{},r)}},g=n.forwardRef((function(e,r){var t=e.components,o=e.mdxType,i=e.originalType,a=e.parentName,s=c(e,["components","mdxType","originalType","parentName"]),p=u(t),l=o,g=p["".concat(a,".").concat(l)]||p[l]||h[l]||i;return t?n.createElement(g,d(d({ref:r},s),{},{components:t})):n.createElement(g,d({ref:r},s))}));function m(e,r){var t=arguments,o=r&&r.mdxType;if("string"==typeof e||o){var i=t.length,a=new Array(i);a[0]=g;var d={};for(var c in r)hasOwnProperty.call(r,c)&&(d[c]=r[c]);d.originalType=e,d.mdxType="string"==typeof e?e:o,a[1]=d;for(var s=2;s{t.r(r),t.d(r,{contentTitle:()=>c,default:()=>l,frontMatter:()=>d,metadata:()=>s,toc:()=>p});var n=t(58168),o=t(98587),i=(t(96540),t(15680)),a=["components"],d={id:"changes_to_job_working_dir",title:"Changes to job's runtime working directory",hide_title:!0},c=void 0,s={unversionedId:"upgrades/1.1_to_1.2/changes_to_job_working_dir",id:"upgrades/1.1_to_1.2/changes_to_job_working_dir",title:"Changes to job's runtime working directory",description:"Hydra 1.2 introduces hydra.job.chdir. This config allows users to specify whether Hydra should change the runtime working",source:"@site/docs/upgrades/1.1_to_1.2/changes_to_job_working_dir.md",sourceDirName:"upgrades/1.1_to_1.2",slug:"/upgrades/1.1_to_1.2/changes_to_job_working_dir",permalink:"/docs/upgrades/1.1_to_1.2/changes_to_job_working_dir",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/upgrades/1.1_to_1.2/changes_to_job_working_dir.md",tags:[],version:"current",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"changes_to_job_working_dir",title:"Changes to job's runtime working directory",hide_title:!0},sidebar:"docs",previous:{title:"Changes to @hydra.main() and hydra.initialize()",permalink:"/docs/upgrades/1.1_to_1.2/changes_to_hydra_main_config_path"},next:{title:"Changes to configuring sweeper's search space",permalink:"/docs/upgrades/1.1_to_1.2/changes_to_sweeper_config"}},p=[],u={toc:p};function l(e){var r=e.components,t=(0,o.A)(e,a);return(0,i.mdx)("wrapper",(0,n.A)({},u,t,{components:r,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Hydra 1.2 introduces ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir"),". This config allows users to specify whether Hydra should change the runtime working\ndirectory to the job's output directory.\n",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir")," will default to ",(0,i.mdx)("inlineCode",{parentName:"p"},"False"),' if version_base is set to >= "1.2" (or None),\nor otherwise will use the old behavior and default to ',(0,i.mdx)("inlineCode",{parentName:"p"},"True"),", with a warning being issued if ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir")," is not set."),(0,i.mdx)("p",null,"If you want to keep the old Hydra behavior, please set ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir=True")," explicitly for your application."),(0,i.mdx)("p",null,"For more information about ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir"),",\nsee ",(0,i.mdx)("a",{parentName:"p",href:"/docs/tutorials/basic/running_your_app/working_directory#disable-changing-current-working-dir-to-jobs-output-dir"},"Output/Working directory"),"\nand ",(0,i.mdx)("a",{parentName:"p",href:"/docs/configure_hydra/job#hydrajobchdir"},"Job Configuration - hydra.job.chdir"),"."))}l.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/0e5950c6.14352803.js b/assets/js/0e5950c6.14352803.js deleted file mode 100644 index 08ce621ef7..0000000000 --- a/assets/js/0e5950c6.14352803.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[7060],{15680:(e,r,t)=>{t.r(r),t.d(r,{MDXContext:()=>s,MDXProvider:()=>l,mdx:()=>m,useMDXComponents:()=>u,withMDXComponents:()=>p});var n=t(96540);function o(e,r,t){return r in e?Object.defineProperty(e,r,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[r]=t,e}function i(){return i=Object.assign||function(e){for(var r=1;r=0||(o[t]=e[t]);return o}(e,r);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(o[t]=e[t])}return o}var s=n.createContext({}),p=function(e){return function(r){var t=u(r.components);return n.createElement(e,i({},r,{components:t}))}},u=function(e){var r=n.useContext(s),t=r;return e&&(t="function"==typeof e?e(r):c(c({},r),e)),t},l=function(e){var r=u(e.components);return n.createElement(s.Provider,{value:r},e.children)},h={inlineCode:"code",wrapper:function(e){var r=e.children;return n.createElement(n.Fragment,{},r)}},g=n.forwardRef((function(e,r){var t=e.components,o=e.mdxType,i=e.originalType,a=e.parentName,s=d(e,["components","mdxType","originalType","parentName"]),p=u(t),l=o,g=p["".concat(a,".").concat(l)]||p[l]||h[l]||i;return t?n.createElement(g,c(c({ref:r},s),{},{components:t})):n.createElement(g,c({ref:r},s))}));function m(e,r){var t=arguments,o=r&&r.mdxType;if("string"==typeof e||o){var i=t.length,a=new Array(i);a[0]=g;var c={};for(var d in r)hasOwnProperty.call(r,d)&&(c[d]=r[d]);c.originalType=e,c.mdxType="string"==typeof e?e:o,a[1]=c;for(var s=2;s{t.r(r),t.d(r,{contentTitle:()=>d,default:()=>l,frontMatter:()=>c,metadata:()=>s,toc:()=>p});var n=t(58168),o=t(98587),i=(t(96540),t(15680)),a=["components"],c={id:"changes_to_job_working_dir",title:"Changes to job's runtime working directory",hide_title:!0},d=void 0,s={unversionedId:"upgrades/1.1_to_1.2/changes_to_job_working_dir",id:"upgrades/1.1_to_1.2/changes_to_job_working_dir",title:"Changes to job's runtime working directory",description:"Hydra 1.2 introduces hydra.job.chdir. This config allows users to specify whether Hydra should change the runtime working",source:"@site/docs/upgrades/1.1_to_1.2/changes_to_job_working_dir.md",sourceDirName:"upgrades/1.1_to_1.2",slug:"/upgrades/1.1_to_1.2/changes_to_job_working_dir",permalink:"/docs/upgrades/1.1_to_1.2/changes_to_job_working_dir",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/upgrades/1.1_to_1.2/changes_to_job_working_dir.md",tags:[],version:"current",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"changes_to_job_working_dir",title:"Changes to job's runtime working directory",hide_title:!0},sidebar:"docs",previous:{title:"Changes to @hydra.main() and hydra.initialize()",permalink:"/docs/upgrades/1.1_to_1.2/changes_to_hydra_main_config_path"},next:{title:"Changes to configuring sweeper's search space",permalink:"/docs/upgrades/1.1_to_1.2/changes_to_sweeper_config"}},p=[],u={toc:p};function l(e){var r=e.components,t=(0,o.A)(e,a);return(0,i.mdx)("wrapper",(0,n.A)({},u,t,{components:r,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Hydra 1.2 introduces ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir"),". This config allows users to specify whether Hydra should change the runtime working\ndirectory to the job's output directory.\n",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir")," will default to ",(0,i.mdx)("inlineCode",{parentName:"p"},"False"),' if version_base is set to >= "1.2" (or None),\nor otherwise will use the old behavior and default to ',(0,i.mdx)("inlineCode",{parentName:"p"},"True"),", with a warning being issued if ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir")," is not set."),(0,i.mdx)("p",null,"If you want to keep the old Hydra behavior, please set ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir=True")," explicitly for your application."),(0,i.mdx)("p",null,"For more information about ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir"),",\nsee ",(0,i.mdx)("a",{parentName:"p",href:"/docs/tutorials/basic/running_your_app/working_directory#disable-changing-current-working-dir-to-jobs-output-dir"},"Output/Working directory"),"\nand ",(0,i.mdx)("a",{parentName:"p",href:"/docs/configure_hydra/job#hydrajobchdir"},"Job Configuration - hydra.job.chdir"),"."))}l.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/0e71d84b.8d4bd34b.js b/assets/js/0e71d84b.8d4bd34b.js deleted file mode 100644 index 2c30c6b53b..0000000000 --- a/assets/js/0e71d84b.8d4bd34b.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[400],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>p,MDXProvider:()=>m,mdx:()=>b,useMDXComponents:()=>s,withMDXComponents:()=>u});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var p=r.createContext({}),u=function(e){return function(t){var n=s(t.components);return r.createElement(e,a({},t,{components:n}))}},s=function(e){var t=r.useContext(p),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},m=function(e){var t=s(e.components);return r.createElement(p.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},f=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,p=c(e,["components","mdxType","originalType","parentName"]),u=s(n),m=o,f=u["".concat(i,".").concat(m)]||u[m]||d[m]||a;return n?r.createElement(f,l(l({ref:t},p),{},{components:n})):r.createElement(f,l({ref:t},p))}));function b(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=n.length,i=new Array(a);i[0]=f;var l={};for(var c in t)hasOwnProperty.call(t,c)&&(l[c]=t[c]);l.originalType=e,l.mdxType="string"==typeof e?e:o,i[1]=l;for(var p=2;p{n.d(t,{A:()=>o});var r=n(96540);function o(e){var t=(0,r.useRef)(null),n=(0,r.useRef)("undefined"!=typeof document?document.createElement("script"):null);return(0,r.useEffect)((function(){t.current.appendChild(n.current)}),[]),(0,r.useEffect)((function(){for(var t in e)e.hasOwnProperty(t)&&(n.current[t]=e[t])})),r.createElement("div",{ref:t})}},64065:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>p,default:()=>d,frontMatter:()=>c,metadata:()=>u,toc:()=>s});var r=n(58168),o=n(98587),a=(n(96540),n(15680)),i=n(57259),l=["components"],c={id:"tab_completion",title:"Tab completion",sidebar_label:"Tab completion"},p=void 0,u={unversionedId:"tutorial/tab_completion",id:"version-0.11/tutorial/tab_completion",title:"Tab completion",description:"You can enable shell TAB completion, for example:",source:"@site/versioned_docs/version-0.11/tutorial/7_tab_completion.md",sourceDirName:"tutorial",slug:"/tutorial/tab_completion",permalink:"/docs/0.11/tutorial/tab_completion",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-0.11/tutorial/7_tab_completion.md",tags:[],version:"0.11",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:7,frontMatter:{id:"tab_completion",title:"Tab completion",sidebar_label:"Tab completion"},sidebar:"version-0.11/docs",previous:{title:"Multi-run",permalink:"/docs/0.11/tutorial/multi-run"},next:{title:"Output/Working directory",permalink:"/docs/0.11/tutorial/working_directory"}},s=[],m={toc:s};function d(e){var t=e.components,n=(0,o.A)(e,l);return(0,a.mdx)("wrapper",(0,r.A)({},m,n,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)("p",null,"You can enable shell TAB completion, for example:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre"},'eval "$(python my_app.py -sc install=SHELL_NAME)"\n')),(0,a.mdx)("p",null,"Get the exact command to install the completion from ",(0,a.mdx)("inlineCode",{parentName:"p"},"--hydra-help"),"."),(0,a.mdx)("p",null,"Replace SHELL_NAME by your shell name, currently, only Bash is supported and we are relying on the community to implement completion plugins for additional shells."),(0,a.mdx)("p",null,"Tab completion can complete config groups, configuration nodes and values and also paths if they start with ",(0,a.mdx)("inlineCode",{parentName:"p"},".")," or ",(0,a.mdx)("inlineCode",{parentName:"p"},"/"),"."),(0,a.mdx)("p",null,"See this short video demonstration of tab completion:"),(0,a.mdx)(i.A,{id:"asciicast-272604",src:"https://asciinema.org/a/272604.js",async:!0,mdxType:"Script"}))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/0e71d84b.d44949c6.js b/assets/js/0e71d84b.d44949c6.js new file mode 100644 index 0000000000..348fe2aa52 --- /dev/null +++ b/assets/js/0e71d84b.d44949c6.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[400],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>p,MDXProvider:()=>m,mdx:()=>b,useMDXComponents:()=>s,withMDXComponents:()=>u});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var p=r.createContext({}),u=function(e){return function(t){var n=s(t.components);return r.createElement(e,a({},t,{components:n}))}},s=function(e){var t=r.useContext(p),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},m=function(e){var t=s(e.components);return r.createElement(p.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},f=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,p=c(e,["components","mdxType","originalType","parentName"]),u=s(n),m=o,f=u["".concat(i,".").concat(m)]||u[m]||d[m]||a;return n?r.createElement(f,l(l({ref:t},p),{},{components:n})):r.createElement(f,l({ref:t},p))}));function b(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=n.length,i=new Array(a);i[0]=f;var l={};for(var c in t)hasOwnProperty.call(t,c)&&(l[c]=t[c]);l.originalType=e,l.mdxType="string"==typeof e?e:o,i[1]=l;for(var p=2;p{n.d(t,{A:()=>o});var r=n(96540);function o(e){var t=(0,r.useRef)(null),n=(0,r.useRef)("undefined"!=typeof document?document.createElement("script"):null);return(0,r.useEffect)((function(){t.current.appendChild(n.current)}),[]),(0,r.useEffect)((function(){for(var t in e)e.hasOwnProperty(t)&&(n.current[t]=e[t])})),r.createElement("div",{ref:t})}},64065:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>p,default:()=>d,frontMatter:()=>c,metadata:()=>u,toc:()=>s});var r=n(58168),o=n(98587),a=(n(96540),n(15680)),i=n(57259),l=["components"],c={id:"tab_completion",title:"Tab completion",sidebar_label:"Tab completion"},p=void 0,u={unversionedId:"tutorial/tab_completion",id:"version-0.11/tutorial/tab_completion",title:"Tab completion",description:"You can enable shell TAB completion, for example:",source:"@site/versioned_docs/version-0.11/tutorial/7_tab_completion.md",sourceDirName:"tutorial",slug:"/tutorial/tab_completion",permalink:"/docs/0.11/tutorial/tab_completion",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-0.11/tutorial/7_tab_completion.md",tags:[],version:"0.11",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:7,frontMatter:{id:"tab_completion",title:"Tab completion",sidebar_label:"Tab completion"},sidebar:"version-0.11/docs",previous:{title:"Multi-run",permalink:"/docs/0.11/tutorial/multi-run"},next:{title:"Output/Working directory",permalink:"/docs/0.11/tutorial/working_directory"}},s=[],m={toc:s};function d(e){var t=e.components,n=(0,o.A)(e,l);return(0,a.mdx)("wrapper",(0,r.A)({},m,n,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)("p",null,"You can enable shell TAB completion, for example:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre"},'eval "$(python my_app.py -sc install=SHELL_NAME)"\n')),(0,a.mdx)("p",null,"Get the exact command to install the completion from ",(0,a.mdx)("inlineCode",{parentName:"p"},"--hydra-help"),"."),(0,a.mdx)("p",null,"Replace SHELL_NAME by your shell name, currently, only Bash is supported and we are relying on the community to implement completion plugins for additional shells."),(0,a.mdx)("p",null,"Tab completion can complete config groups, configuration nodes and values and also paths if they start with ",(0,a.mdx)("inlineCode",{parentName:"p"},".")," or ",(0,a.mdx)("inlineCode",{parentName:"p"},"/"),"."),(0,a.mdx)("p",null,"See this short video demonstration of tab completion:"),(0,a.mdx)(i.A,{id:"asciicast-272604",src:"https://asciinema.org/a/272604.js",async:!0,mdxType:"Script"}))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/0fa51aec.6e8bdc53.js b/assets/js/0fa51aec.6e8bdc53.js new file mode 100644 index 0000000000..9bf3c228ae --- /dev/null +++ b/assets/js/0fa51aec.6e8bdc53.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[4969],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>l,MDXProvider:()=>m,mdx:()=>f,useMDXComponents:()=>p,withMDXComponents:()=>d});var r=n(96540);function a(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(a[n]=e[n]);return a}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(a[n]=e[n])}return a}var l=r.createContext({}),d=function(e){return function(t){var n=p(t.components);return r.createElement(e,o({},t,{components:n}))}},p=function(e){var t=r.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):s(s({},t),e)),n},m=function(e){var t=p(e.components);return r.createElement(l.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},g=r.forwardRef((function(e,t){var n=e.components,a=e.mdxType,o=e.originalType,i=e.parentName,l=c(e,["components","mdxType","originalType","parentName"]),d=p(n),m=a,g=d["".concat(i,".").concat(m)]||d[m]||u[m]||o;return n?r.createElement(g,s(s({ref:t},l),{},{components:n})):r.createElement(g,s({ref:t},l))}));function f(e,t){var n=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var o=n.length,i=new Array(o);i[0]=g;var s={};for(var c in t)hasOwnProperty.call(t,c)&&(s[c]=t[c]);s.originalType=e,s.mdxType="string"==typeof e?e:a,i[1]=s;for(var l=2;l{n.r(t),n.d(t,{contentTitle:()=>c,default:()=>m,frontMatter:()=>s,metadata:()=>l,toc:()=>d});var r=n(58168),a=n(98587),o=(n(96540),n(15680)),i=["components"],s={id:"object_instantiation_changes",title:"Object instantiation changes",hide_title:!0},c=void 0,l={unversionedId:"upgrades/0.11_to_1.0/object_instantiation_changes",id:"version-1.1/upgrades/0.11_to_1.0/object_instantiation_changes",title:"Object instantiation changes",description:"Object instantiation changes",source:"@site/versioned_docs/version-1.1/upgrades/0.11_to_1.0/object_instantiation_changes.md",sourceDirName:"upgrades/0.11_to_1.0",slug:"/upgrades/0.11_to_1.0/object_instantiation_changes",permalink:"/docs/1.1/upgrades/0.11_to_1.0/object_instantiation_changes",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/upgrades/0.11_to_1.0/object_instantiation_changes.md",tags:[],version:"1.1",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"object_instantiation_changes",title:"Object instantiation changes",hide_title:!0},sidebar:"version-1.1/docs",previous:{title:"strict flag mode deprecation",permalink:"/docs/1.1/upgrades/0.11_to_1.0/strict_mode_flag_deprecated"}},d=[{value:"Object instantiation changes",id:"object-instantiation-changes",children:[],level:2},{value:"Hydra configuration",id:"hydra-configuration",children:[],level:2}],p={toc:d};function m(e){var t=e.components,n=(0,a.A)(e,i);return(0,o.mdx)("wrapper",(0,r.A)({},p,n,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)("h2",{id:"object-instantiation-changes"},"Object instantiation changes"),(0,o.mdx)("p",null,"Hydra 1.0.0 is deprecating ObjectConf and the corresponding config structure to a simpler one without the params node.\nThis removes a level of nesting from command line and configs overrides."),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Hydra 0.11"',title:'"Hydra','0.11"':!0},"class: my_app.MySQLConnection\nparams:\n host: localhost\n user: root\n password: 1234\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Hydra 1.0"',title:'"Hydra','1.0"':!0},"_target_: my_app.MySQLConnection\nhost: localhost\nuser: root\npassword: 1234\n\n")))),(0,o.mdx)("h2",{id:"hydra-configuration"},"Hydra configuration"),(0,o.mdx)("p",null,"Hydra plugins are configured using the same mechanism.\nThis means that this change will effect how all plugins are configured and overridden.\nThis is a breaking change for code overriding configs in such plugins, but luckily it's easy to fix."),(0,o.mdx)("p",null,"As an example, a Sweeper plugin override will change as follows:"),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-shell",metastring:'script title="Hydra 0.11"',script:!0,title:'"Hydra','0.11"':!0},"hydra.sweeper.params.max_batch_size=10\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-shell",metastring:'script title="Hydra 1.0"',script:!0,title:'"Hydra','1.0"':!0},"hydra.sweeper.max_batch_size=10\n")))))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/0fa51aec.c04e2e1c.js b/assets/js/0fa51aec.c04e2e1c.js deleted file mode 100644 index 2cc04ec043..0000000000 --- a/assets/js/0fa51aec.c04e2e1c.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[4969],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>l,MDXProvider:()=>m,mdx:()=>f,useMDXComponents:()=>p,withMDXComponents:()=>d});var r=n(96540);function a(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(a[n]=e[n]);return a}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(a[n]=e[n])}return a}var l=r.createContext({}),d=function(e){return function(t){var n=p(t.components);return r.createElement(e,o({},t,{components:n}))}},p=function(e){var t=r.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):s(s({},t),e)),n},m=function(e){var t=p(e.components);return r.createElement(l.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},g=r.forwardRef((function(e,t){var n=e.components,a=e.mdxType,o=e.originalType,i=e.parentName,l=c(e,["components","mdxType","originalType","parentName"]),d=p(n),m=a,g=d["".concat(i,".").concat(m)]||d[m]||u[m]||o;return n?r.createElement(g,s(s({ref:t},l),{},{components:n})):r.createElement(g,s({ref:t},l))}));function f(e,t){var n=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var o=n.length,i=new Array(o);i[0]=g;var s={};for(var c in t)hasOwnProperty.call(t,c)&&(s[c]=t[c]);s.originalType=e,s.mdxType="string"==typeof e?e:a,i[1]=s;for(var l=2;l{n.r(t),n.d(t,{contentTitle:()=>c,default:()=>m,frontMatter:()=>s,metadata:()=>l,toc:()=>d});var r=n(58168),a=n(98587),o=(n(96540),n(15680)),i=["components"],s={id:"object_instantiation_changes",title:"Object instantiation changes",hide_title:!0},c=void 0,l={unversionedId:"upgrades/0.11_to_1.0/object_instantiation_changes",id:"version-1.1/upgrades/0.11_to_1.0/object_instantiation_changes",title:"Object instantiation changes",description:"Object instantiation changes",source:"@site/versioned_docs/version-1.1/upgrades/0.11_to_1.0/object_instantiation_changes.md",sourceDirName:"upgrades/0.11_to_1.0",slug:"/upgrades/0.11_to_1.0/object_instantiation_changes",permalink:"/docs/1.1/upgrades/0.11_to_1.0/object_instantiation_changes",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/upgrades/0.11_to_1.0/object_instantiation_changes.md",tags:[],version:"1.1",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"object_instantiation_changes",title:"Object instantiation changes",hide_title:!0},sidebar:"version-1.1/docs",previous:{title:"strict flag mode deprecation",permalink:"/docs/1.1/upgrades/0.11_to_1.0/strict_mode_flag_deprecated"}},d=[{value:"Object instantiation changes",id:"object-instantiation-changes",children:[],level:2},{value:"Hydra configuration",id:"hydra-configuration",children:[],level:2}],p={toc:d};function m(e){var t=e.components,n=(0,a.A)(e,i);return(0,o.mdx)("wrapper",(0,r.A)({},p,n,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)("h2",{id:"object-instantiation-changes"},"Object instantiation changes"),(0,o.mdx)("p",null,"Hydra 1.0.0 is deprecating ObjectConf and the corresponding config structure to a simpler one without the params node.\nThis removes a level of nesting from command line and configs overrides."),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Hydra 0.11"',title:'"Hydra','0.11"':!0},"class: my_app.MySQLConnection\nparams:\n host: localhost\n user: root\n password: 1234\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Hydra 1.0"',title:'"Hydra','1.0"':!0},"_target_: my_app.MySQLConnection\nhost: localhost\nuser: root\npassword: 1234\n\n")))),(0,o.mdx)("h2",{id:"hydra-configuration"},"Hydra configuration"),(0,o.mdx)("p",null,"Hydra plugins are configured using the same mechanism.\nThis means that this change will effect how all plugins are configured and overridden.\nThis is a breaking change for code overriding configs in such plugins, but luckily it's easy to fix."),(0,o.mdx)("p",null,"As an example, a Sweeper plugin override will change as follows:"),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-shell",metastring:'script title="Hydra 0.11"',script:!0,title:'"Hydra','0.11"':!0},"hydra.sweeper.params.max_batch_size=10\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-shell",metastring:'script title="Hydra 1.0"',script:!0,title:'"Hydra','1.0"':!0},"hydra.sweeper.max_batch_size=10\n")))))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/10abfaeb.0336187a.js b/assets/js/10abfaeb.0336187a.js deleted file mode 100644 index 50fe168e0f..0000000000 --- a/assets/js/10abfaeb.0336187a.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3523],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>s,MDXProvider:()=>p,mdx:()=>g,useMDXComponents:()=>c,withMDXComponents:()=>m});var a=n(96540);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var s=a.createContext({}),m=function(e){return function(t){var n=c(t.components);return a.createElement(e,o({},t,{components:n}))}},c=function(e){var t=a.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},p=function(e){var t=c(e.components);return a.createElement(s.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},f=a.forwardRef((function(e,t){var n=e.components,i=e.mdxType,o=e.originalType,r=e.parentName,s=d(e,["components","mdxType","originalType","parentName"]),m=c(n),p=i,f=m["".concat(r,".").concat(p)]||m[p]||u[p]||o;return n?a.createElement(f,l(l({ref:t},s),{},{components:n})):a.createElement(f,l({ref:t},s))}));function g(e,t){var n=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var o=n.length,r=new Array(o);r[0]=f;var l={};for(var d in t)hasOwnProperty.call(t,d)&&(l[d]=t[d]);l.originalType=e,l.mdxType="string"==typeof e?e:i,r[1]=l;for(var s=2;s{n.d(t,{A:()=>d,C:()=>s});var a=n(58168),i=n(96540),o=n(75489),r=n(44586),l=n(74098);function d(e){return i.createElement(o.default,(0,a.A)({},e,{to:(t=e.to,d=(0,l.useActiveVersion)(),(0,r.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==d?void 0:d.name)?n:"current"]+t),target:"_blank"}));var t,n,d}function s(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return i.createElement(d,e,i.createElement("span",null,"\xa0"),i.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},63770:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>s,default:()=>u,frontMatter:()=>d,metadata:()=>m,toc:()=>c});var a=n(58168),i=n(98587),o=(n(96540),n(15680)),r=n(49595),l=["components"],d={id:"specializing_config",title:"Specializing configuration"},s=void 0,m={unversionedId:"patterns/specializing_config",id:"version-1.2/patterns/specializing_config",title:"Specializing configuration",description:"In some cases the desired configuration should depend on other configuration choices.",source:"@site/versioned_docs/version-1.2/patterns/specializing_config.md",sourceDirName:"patterns",slug:"/patterns/specializing_config",permalink:"/docs/1.2/patterns/specializing_config",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/patterns/specializing_config.md",tags:[],version:"1.2",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"specializing_config",title:"Specializing configuration"},sidebar:"docs",previous:{title:"Selecting multiple configs from a Config Group",permalink:"/docs/1.2/patterns/select_multiple_configs_from_config_group"},next:{title:"Read-only config",permalink:"/docs/1.2/patterns/write_protect_config_node"}},c=[{value:"initial config.yaml",id:"initial-configyaml",children:[],level:3},{value:"modified config.yaml",id:"modified-configyaml",children:[{value:"dataset_model",id:"dataset_model",children:[],level:4},{value:"${dataset}_${model}",id:"dataset_model-1",children:[],level:4},{value:"optional",id:"optional",children:[],level:4}],level:3},{value:"dataset_model/cifar10_alexnet.yaml",id:"dataset_modelcifar10_alexnetyaml",children:[],level:3}],p={toc:c};function u(e){var t=e.components,n=(0,i.A)(e,l);return(0,o.mdx)("wrapper",(0,a.A)({},p,n,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)(r.C,{text:"Example application",to:"examples/patterns/specializing_config",mdxType:"ExampleGithubLink"}),(0,o.mdx)("p",null,"In some cases the desired configuration should depend on other configuration choices.\nFor example, You may want to use only 5 layers in your Alexnet model if the dataset of choice is cifar10, and the default 7 otherwise."),(0,o.mdx)("p",null,"We can start with a config that looks like this:"),(0,o.mdx)("h3",{id:"initial-configyaml"},"initial config.yaml"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - dataset: imagenet\n - model: alexnet\n")),(0,o.mdx)("p",null,"We want to specialize the config based on the choice of the selected dataset and model:\nFurthermore, we only want to do it for cifar10 and alexnet and not for 3 other combinations."),(0,o.mdx)("p",null,"OmegaConf supports value interpolation, we can construct a value that would - at runtime - be a function of other values.\nThe idea is that we can add another element to the defaults list that would load a file name that depends on those two values:"),(0,o.mdx)("h3",{id:"modified-configyaml"},"modified config.yaml"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - dataset: imagenet\n - model: alexnet\n - optional dataset_model: ${dataset}_${model}\n")),(0,o.mdx)("p",null,"Let's break this down:"),(0,o.mdx)("h4",{id:"dataset_model"},"dataset_model"),(0,o.mdx)("p",null,"The key ",(0,o.mdx)("inlineCode",{parentName:"p"},"dataset_model")," is an arbitrary directory, it can be anything unique that makes sense, including nested directory like ",(0,o.mdx)("inlineCode",{parentName:"p"},"dataset/model"),"."),(0,o.mdx)("h4",{id:"dataset_model-1"},"${dataset}_${model}"),(0,o.mdx)("p",null,"the value ",(0,o.mdx)("inlineCode",{parentName:"p"},"${dataset}_${model}")," is using OmegaConf's ",(0,o.mdx)("a",{parentName:"p",href:"https://omegaconf.readthedocs.io/en/latest/usage.html#variable-interpolation"},"variable interpolation")," syntax.\nAt runtime, that value would resolve to ",(0,o.mdx)("em",{parentName:"p"},"imagenet_alexnet"),", or ",(0,o.mdx)("em",{parentName:"p"},"cifar_resnet")," - depending on the values of defaults.dataset and defaults.model."),(0,o.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,o.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,o.mdx)("h5",{parentName:"div"},(0,o.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,o.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,o.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"info")),(0,o.mdx)("div",{parentName:"div",className:"admonition-content"},(0,o.mdx)("p",{parentName:"div"},"This is non-standard interpolation and there are some subtle differences and limitations."))),(0,o.mdx)("h4",{id:"optional"},"optional"),(0,o.mdx)("p",null,"By default, Hydra fails with an error if a config specified in the defaults does not exist.\nIn this case we only want to specialize cifar10 + alexnet, not all 4 combinations.\nthe keyword ",(0,o.mdx)("inlineCode",{parentName:"p"},"optional")," tells Hydra to just continue if it can't find this file."),(0,o.mdx)("p",null,"When specializing config, you usually want to only specify what's different, and not the whole thing.\nWe want the model for alexnet, when trained on cifar - to have 5 layers."),(0,o.mdx)("h3",{id:"dataset_modelcifar10_alexnetyaml"},"dataset_model/cifar10_alexnet.yaml"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"# @package _global_\n\nmodel:\n num_layers: 5\n")),(0,o.mdx)("p",null,"Let's check. Running with the default uses imagenet, so we don't get the specialized version of:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python example.py \ndataset:\n name: imagenet\n path: /datasets/imagenet\nmodel:\n num_layers: 7\n type: alexnet\n")),(0,o.mdx)("p",null,"Running with cifar10 dataset, we do get 5 for num_layers:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python example.py dataset=cifar10\ndataset:\n name: cifar10\n path: /datasets/cifar10\nmodel:\n num_layers: 5\n type: alexnet\n")))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/10abfaeb.4459970b.js b/assets/js/10abfaeb.4459970b.js new file mode 100644 index 0000000000..6e30828835 --- /dev/null +++ b/assets/js/10abfaeb.4459970b.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3523],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>s,MDXProvider:()=>p,mdx:()=>g,useMDXComponents:()=>c,withMDXComponents:()=>m});var a=n(96540);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var s=a.createContext({}),m=function(e){return function(t){var n=c(t.components);return a.createElement(e,o({},t,{components:n}))}},c=function(e){var t=a.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},p=function(e){var t=c(e.components);return a.createElement(s.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},f=a.forwardRef((function(e,t){var n=e.components,i=e.mdxType,o=e.originalType,r=e.parentName,s=d(e,["components","mdxType","originalType","parentName"]),m=c(n),p=i,f=m["".concat(r,".").concat(p)]||m[p]||u[p]||o;return n?a.createElement(f,l(l({ref:t},s),{},{components:n})):a.createElement(f,l({ref:t},s))}));function g(e,t){var n=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var o=n.length,r=new Array(o);r[0]=f;var l={};for(var d in t)hasOwnProperty.call(t,d)&&(l[d]=t[d]);l.originalType=e,l.mdxType="string"==typeof e?e:i,r[1]=l;for(var s=2;s{n.d(t,{A:()=>d,C:()=>s});var a=n(58168),i=n(96540),o=n(75489),r=n(44586),l=n(74098);function d(e){return i.createElement(o.default,(0,a.A)({},e,{to:(t=e.to,d=(0,l.useActiveVersion)(),(0,r.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==d?void 0:d.name)?n:"current"]+t),target:"_blank"}));var t,n,d}function s(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return i.createElement(d,e,i.createElement("span",null,"\xa0"),i.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},63770:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>s,default:()=>u,frontMatter:()=>d,metadata:()=>m,toc:()=>c});var a=n(58168),i=n(98587),o=(n(96540),n(15680)),r=n(49595),l=["components"],d={id:"specializing_config",title:"Specializing configuration"},s=void 0,m={unversionedId:"patterns/specializing_config",id:"version-1.2/patterns/specializing_config",title:"Specializing configuration",description:"In some cases the desired configuration should depend on other configuration choices.",source:"@site/versioned_docs/version-1.2/patterns/specializing_config.md",sourceDirName:"patterns",slug:"/patterns/specializing_config",permalink:"/docs/1.2/patterns/specializing_config",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/patterns/specializing_config.md",tags:[],version:"1.2",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"specializing_config",title:"Specializing configuration"},sidebar:"docs",previous:{title:"Selecting multiple configs from a Config Group",permalink:"/docs/1.2/patterns/select_multiple_configs_from_config_group"},next:{title:"Read-only config",permalink:"/docs/1.2/patterns/write_protect_config_node"}},c=[{value:"initial config.yaml",id:"initial-configyaml",children:[],level:3},{value:"modified config.yaml",id:"modified-configyaml",children:[{value:"dataset_model",id:"dataset_model",children:[],level:4},{value:"${dataset}_${model}",id:"dataset_model-1",children:[],level:4},{value:"optional",id:"optional",children:[],level:4}],level:3},{value:"dataset_model/cifar10_alexnet.yaml",id:"dataset_modelcifar10_alexnetyaml",children:[],level:3}],p={toc:c};function u(e){var t=e.components,n=(0,i.A)(e,l);return(0,o.mdx)("wrapper",(0,a.A)({},p,n,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)(r.C,{text:"Example application",to:"examples/patterns/specializing_config",mdxType:"ExampleGithubLink"}),(0,o.mdx)("p",null,"In some cases the desired configuration should depend on other configuration choices.\nFor example, You may want to use only 5 layers in your Alexnet model if the dataset of choice is cifar10, and the default 7 otherwise."),(0,o.mdx)("p",null,"We can start with a config that looks like this:"),(0,o.mdx)("h3",{id:"initial-configyaml"},"initial config.yaml"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - dataset: imagenet\n - model: alexnet\n")),(0,o.mdx)("p",null,"We want to specialize the config based on the choice of the selected dataset and model:\nFurthermore, we only want to do it for cifar10 and alexnet and not for 3 other combinations."),(0,o.mdx)("p",null,"OmegaConf supports value interpolation, we can construct a value that would - at runtime - be a function of other values.\nThe idea is that we can add another element to the defaults list that would load a file name that depends on those two values:"),(0,o.mdx)("h3",{id:"modified-configyaml"},"modified config.yaml"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - dataset: imagenet\n - model: alexnet\n - optional dataset_model: ${dataset}_${model}\n")),(0,o.mdx)("p",null,"Let's break this down:"),(0,o.mdx)("h4",{id:"dataset_model"},"dataset_model"),(0,o.mdx)("p",null,"The key ",(0,o.mdx)("inlineCode",{parentName:"p"},"dataset_model")," is an arbitrary directory, it can be anything unique that makes sense, including nested directory like ",(0,o.mdx)("inlineCode",{parentName:"p"},"dataset/model"),"."),(0,o.mdx)("h4",{id:"dataset_model-1"},"${dataset}_${model}"),(0,o.mdx)("p",null,"the value ",(0,o.mdx)("inlineCode",{parentName:"p"},"${dataset}_${model}")," is using OmegaConf's ",(0,o.mdx)("a",{parentName:"p",href:"https://omegaconf.readthedocs.io/en/latest/usage.html#variable-interpolation"},"variable interpolation")," syntax.\nAt runtime, that value would resolve to ",(0,o.mdx)("em",{parentName:"p"},"imagenet_alexnet"),", or ",(0,o.mdx)("em",{parentName:"p"},"cifar_resnet")," - depending on the values of defaults.dataset and defaults.model."),(0,o.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,o.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,o.mdx)("h5",{parentName:"div"},(0,o.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,o.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,o.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"info")),(0,o.mdx)("div",{parentName:"div",className:"admonition-content"},(0,o.mdx)("p",{parentName:"div"},"This is non-standard interpolation and there are some subtle differences and limitations."))),(0,o.mdx)("h4",{id:"optional"},"optional"),(0,o.mdx)("p",null,"By default, Hydra fails with an error if a config specified in the defaults does not exist.\nIn this case we only want to specialize cifar10 + alexnet, not all 4 combinations.\nthe keyword ",(0,o.mdx)("inlineCode",{parentName:"p"},"optional")," tells Hydra to just continue if it can't find this file."),(0,o.mdx)("p",null,"When specializing config, you usually want to only specify what's different, and not the whole thing.\nWe want the model for alexnet, when trained on cifar - to have 5 layers."),(0,o.mdx)("h3",{id:"dataset_modelcifar10_alexnetyaml"},"dataset_model/cifar10_alexnet.yaml"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"# @package _global_\n\nmodel:\n num_layers: 5\n")),(0,o.mdx)("p",null,"Let's check. Running with the default uses imagenet, so we don't get the specialized version of:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python example.py \ndataset:\n name: imagenet\n path: /datasets/imagenet\nmodel:\n num_layers: 7\n type: alexnet\n")),(0,o.mdx)("p",null,"Running with cifar10 dataset, we do get 5 for num_layers:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python example.py dataset=cifar10\ndataset:\n name: cifar10\n path: /datasets/cifar10\nmodel:\n num_layers: 5\n type: alexnet\n")))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/10c36d6f.47c46354.js b/assets/js/10c36d6f.47c46354.js deleted file mode 100644 index 90576dc39c..0000000000 --- a/assets/js/10c36d6f.47c46354.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[8252],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>c,MDXProvider:()=>f,mdx:()=>g,useMDXComponents:()=>p,withMDXComponents:()=>d});var a=n(96540);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var c=a.createContext({}),d=function(e){return function(t){var n=p(t.components);return a.createElement(e,o({},t,{components:n}))}},p=function(e){var t=a.useContext(c),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},f=function(e){var t=p(e.components);return a.createElement(c.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},u=a.forwardRef((function(e,t){var n=e.components,r=e.mdxType,o=e.originalType,s=e.parentName,c=l(e,["components","mdxType","originalType","parentName"]),d=p(n),f=r,u=d["".concat(s,".").concat(f)]||d[f]||m[f]||o;return n?a.createElement(u,i(i({ref:t},c),{},{components:n})):a.createElement(u,i({ref:t},c))}));function g(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var o=n.length,s=new Array(o);s[0]=u;var i={};for(var l in t)hasOwnProperty.call(t,l)&&(i[l]=t[l]);i.originalType=e,i.mdxType="string"==typeof e?e:r,s[1]=i;for(var c=2;c{n.d(t,{A:()=>l,C:()=>c});var a=n(58168),r=n(96540),o=n(75489),s=n(44586),i=n(74098);function l(e){return r.createElement(o.default,(0,a.A)({},e,{to:(t=e.to,l=(0,i.useActiveVersion)(),(0,s.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==l?void 0:l.name)?n:"current"]+t),target:"_blank"}));var t,n,l}function c(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return r.createElement(l,e,r.createElement("span",null,"\xa0"),r.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},57509:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>c,default:()=>m,frontMatter:()=>l,metadata:()=>d,toc:()=>p});var a=n(58168),r=n(98587),o=(n(96540),n(15680)),s=n(49595),i=["components"],l={id:"config_files",title:"Config files example",sidebar_label:"Config files example"},c=void 0,d={unversionedId:"advanced/instantiate_objects/config_files",id:"version-1.1/advanced/instantiate_objects/config_files",title:"Config files example",description:"This example demonstrates the use of config files to instantiated objects.",source:"@site/versioned_docs/version-1.1/advanced/instantiate_objects/config_files.md",sourceDirName:"advanced/instantiate_objects",slug:"/advanced/instantiate_objects/config_files",permalink:"/docs/1.1/advanced/instantiate_objects/config_files",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/advanced/instantiate_objects/config_files.md",tags:[],version:"1.1",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"config_files",title:"Config files example",sidebar_label:"Config files example"},sidebar:"version-1.1/docs",previous:{title:"Overview",permalink:"/docs/1.1/advanced/instantiate_objects/overview"},next:{title:"Structured Configs example",permalink:"/docs/1.1/advanced/instantiate_objects/structured_config"}},p=[],f={toc:p};function m(e){var t=e.components,n=(0,r.A)(e,i);return(0,o.mdx)("wrapper",(0,a.A)({},f,n,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)(s.C,{text:"Example applications",to:"examples/instantiate",mdxType:"ExampleGithubLink"}),(0,o.mdx)("p",null,"This example demonstrates the use of config files to instantiated objects."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'class DBConnection:\n def connect(self):\n ...\n\nclass MySQLConnection(DBConnection):\n def __init__(self, host: str, user: str, password: str) -> None:\n self.host = host\n self.user = user\n self.password = password\n\n def connect(self) -> None:\n print(f"MySQL connecting to {self.host}")\n\n\nclass PostgreSQLConnection(DBConnection):\n def __init__(self, host: str, user: str, password: str, database: str) -> None:\n self.host = host\n self.user = user\n self.password = password\n self.database = database\n\n def connect(self) -> None:\n print(f"PostgreSQL connecting to {self.host}")\n')),(0,o.mdx)("p",null,"To support this, we can have a parallel config structure:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-text"},"conf/\n\u251c\u2500\u2500 config.yaml\n\u2514\u2500\u2500 db\n \u251c\u2500\u2500 mysql.yaml\n \u2514\u2500\u2500 postgresql.yaml\n")),(0,o.mdx)("p",null,"Config files:"),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml"',title:'"db/mysql.yaml"'},"_target_: my_app.MySQLConnection\nhost: localhost\nuser: root\npassword: 1234\n\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/postgresql.yaml"',title:'"db/postgresql.yaml"'},"_target_: my_app.PostgreSQLConnection\nhost: localhost\nuser: root\npassword: 1234\ndatabase: tutorial\n")))),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - db: mysql\n")),(0,o.mdx)("p",null,"With this, you can instantiate the object from the configuration with a single line of code:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'@hydra.main(config_path="conf", config_name="config")\ndef my_app(cfg):\n connection = hydra.utils.instantiate(cfg.db)\n connection.connect()\n')))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/10c36d6f.bdc82066.js b/assets/js/10c36d6f.bdc82066.js new file mode 100644 index 0000000000..da89088cf9 --- /dev/null +++ b/assets/js/10c36d6f.bdc82066.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[8252],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>c,MDXProvider:()=>f,mdx:()=>g,useMDXComponents:()=>p,withMDXComponents:()=>d});var a=n(96540);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var c=a.createContext({}),d=function(e){return function(t){var n=p(t.components);return a.createElement(e,o({},t,{components:n}))}},p=function(e){var t=a.useContext(c),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},f=function(e){var t=p(e.components);return a.createElement(c.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},u=a.forwardRef((function(e,t){var n=e.components,r=e.mdxType,o=e.originalType,s=e.parentName,c=l(e,["components","mdxType","originalType","parentName"]),d=p(n),f=r,u=d["".concat(s,".").concat(f)]||d[f]||m[f]||o;return n?a.createElement(u,i(i({ref:t},c),{},{components:n})):a.createElement(u,i({ref:t},c))}));function g(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var o=n.length,s=new Array(o);s[0]=u;var i={};for(var l in t)hasOwnProperty.call(t,l)&&(i[l]=t[l]);i.originalType=e,i.mdxType="string"==typeof e?e:r,s[1]=i;for(var c=2;c{n.d(t,{A:()=>l,C:()=>c});var a=n(58168),r=n(96540),o=n(75489),s=n(44586),i=n(74098);function l(e){return r.createElement(o.default,(0,a.A)({},e,{to:(t=e.to,l=(0,i.useActiveVersion)(),(0,s.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==l?void 0:l.name)?n:"current"]+t),target:"_blank"}));var t,n,l}function c(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return r.createElement(l,e,r.createElement("span",null,"\xa0"),r.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},57509:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>c,default:()=>m,frontMatter:()=>l,metadata:()=>d,toc:()=>p});var a=n(58168),r=n(98587),o=(n(96540),n(15680)),s=n(49595),i=["components"],l={id:"config_files",title:"Config files example",sidebar_label:"Config files example"},c=void 0,d={unversionedId:"advanced/instantiate_objects/config_files",id:"version-1.1/advanced/instantiate_objects/config_files",title:"Config files example",description:"This example demonstrates the use of config files to instantiated objects.",source:"@site/versioned_docs/version-1.1/advanced/instantiate_objects/config_files.md",sourceDirName:"advanced/instantiate_objects",slug:"/advanced/instantiate_objects/config_files",permalink:"/docs/1.1/advanced/instantiate_objects/config_files",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/advanced/instantiate_objects/config_files.md",tags:[],version:"1.1",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"config_files",title:"Config files example",sidebar_label:"Config files example"},sidebar:"version-1.1/docs",previous:{title:"Overview",permalink:"/docs/1.1/advanced/instantiate_objects/overview"},next:{title:"Structured Configs example",permalink:"/docs/1.1/advanced/instantiate_objects/structured_config"}},p=[],f={toc:p};function m(e){var t=e.components,n=(0,r.A)(e,i);return(0,o.mdx)("wrapper",(0,a.A)({},f,n,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)(s.C,{text:"Example applications",to:"examples/instantiate",mdxType:"ExampleGithubLink"}),(0,o.mdx)("p",null,"This example demonstrates the use of config files to instantiated objects."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'class DBConnection:\n def connect(self):\n ...\n\nclass MySQLConnection(DBConnection):\n def __init__(self, host: str, user: str, password: str) -> None:\n self.host = host\n self.user = user\n self.password = password\n\n def connect(self) -> None:\n print(f"MySQL connecting to {self.host}")\n\n\nclass PostgreSQLConnection(DBConnection):\n def __init__(self, host: str, user: str, password: str, database: str) -> None:\n self.host = host\n self.user = user\n self.password = password\n self.database = database\n\n def connect(self) -> None:\n print(f"PostgreSQL connecting to {self.host}")\n')),(0,o.mdx)("p",null,"To support this, we can have a parallel config structure:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-text"},"conf/\n\u251c\u2500\u2500 config.yaml\n\u2514\u2500\u2500 db\n \u251c\u2500\u2500 mysql.yaml\n \u2514\u2500\u2500 postgresql.yaml\n")),(0,o.mdx)("p",null,"Config files:"),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml"',title:'"db/mysql.yaml"'},"_target_: my_app.MySQLConnection\nhost: localhost\nuser: root\npassword: 1234\n\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/postgresql.yaml"',title:'"db/postgresql.yaml"'},"_target_: my_app.PostgreSQLConnection\nhost: localhost\nuser: root\npassword: 1234\ndatabase: tutorial\n")))),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - db: mysql\n")),(0,o.mdx)("p",null,"With this, you can instantiate the object from the configuration with a single line of code:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'@hydra.main(config_path="conf", config_name="config")\ndef my_app(cfg):\n connection = hydra.utils.instantiate(cfg.db)\n connection.connect()\n')))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/10dd8346.8f5d83b4.js b/assets/js/10dd8346.8f5d83b4.js deleted file mode 100644 index 6f8a4afe34..0000000000 --- a/assets/js/10dd8346.8f5d83b4.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3893],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>l,MDXProvider:()=>d,mdx:()=>f,useMDXComponents:()=>m,withMDXComponents:()=>c});var r=t(96540);function o(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function a(){return a=Object.assign||function(e){for(var n=1;n=0||(o[t]=e[t]);return o}(e,n);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(o[t]=e[t])}return o}var l=r.createContext({}),c=function(e){return function(n){var t=m(n.components);return r.createElement(e,a({},n,{components:t}))}},m=function(e){var n=r.useContext(l),t=n;return e&&(t="function"==typeof e?e(n):p(p({},n),e)),t},d=function(e){var n=m(e.components);return r.createElement(l.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},g=r.forwardRef((function(e,n){var t=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,l=s(e,["components","mdxType","originalType","parentName"]),c=m(t),d=o,g=c["".concat(i,".").concat(d)]||c[d]||u[d]||a;return t?r.createElement(g,p(p({ref:n},l),{},{components:t})):r.createElement(g,p({ref:n},l))}));function f(e,n){var t=arguments,o=n&&n.mdxType;if("string"==typeof e||o){var a=t.length,i=new Array(a);i[0]=g;var p={};for(var s in n)hasOwnProperty.call(n,s)&&(p[s]=n[s]);p.originalType=e,p.mdxType="string"==typeof e?e:o,i[1]=p;for(var l=2;l{t.d(n,{A:()=>s,C:()=>l});var r=t(58168),o=t(96540),a=t(75489),i=t(44586),p=t(74098);function s(e){return o.createElement(a.default,(0,r.A)({},e,{to:(n=e.to,s=(0,p.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==s?void 0:s.name)?t:"current"]+n),target:"_blank"}));var n,t,s}function l(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return o.createElement(s,e,o.createElement("span",null,"\xa0"),o.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},39390:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>l,default:()=>u,frontMatter:()=>s,metadata:()=>c,toc:()=>m});var r=t(58168),o=t(98587),a=(t(96540),t(15680)),i=t(49595),p=["components"],s={id:"config_groups",title:"Grouping config files"},l=void 0,c={unversionedId:"tutorials/basic/your_first_app/config_groups",id:"version-1.3/tutorials/basic/your_first_app/config_groups",title:"Grouping config files",description:"Suppose you want to benchmark your application on each of PostgreSQL and MySQL. To do this, use config groups.",source:"@site/versioned_docs/version-1.3/tutorials/basic/your_first_app/4_config_groups.md",sourceDirName:"tutorials/basic/your_first_app",slug:"/tutorials/basic/your_first_app/config_groups",permalink:"/docs/1.3/tutorials/basic/your_first_app/config_groups",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/tutorials/basic/your_first_app/4_config_groups.md",tags:[],version:"1.3",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:4,frontMatter:{id:"config_groups",title:"Grouping config files"},sidebar:"docs",previous:{title:"Using the config object",permalink:"/docs/1.3/tutorials/basic/your_first_app/using_config"},next:{title:"Selecting default configs",permalink:"/docs/1.3/tutorials/basic/your_first_app/defaults"}},m=[{value:"Creating config groups",id:"creating-config-groups",children:[],level:3},{value:"Using config groups",id:"using-config-groups",children:[],level:3},{value:"Advanced topics",id:"advanced-topics",children:[],level:3}],d={toc:m};function u(e){var n=e.components,t=(0,o.A)(e,p);return(0,a.mdx)("wrapper",(0,r.A)({},d,t,{components:n,mdxType:"MDXLayout"}),(0,a.mdx)(i.C,{to:"examples/tutorials/basic/your_first_hydra_app/4_config_groups",mdxType:"ExampleGithubLink"}),(0,a.mdx)("p",null,"Suppose you want to benchmark your application on each of PostgreSQL and MySQL. To do this, use config groups. "),(0,a.mdx)("p",null,"A ",(0,a.mdx)("em",{parentName:"p"},(0,a.mdx)("strong",{parentName:"em"},"Config Group"))," is a named group with a set of valid options.\nSelecting a non-existent config option generates an error message with the valid options."),(0,a.mdx)("h3",{id:"creating-config-groups"},"Creating config groups"),(0,a.mdx)("p",null,"To create a config group, create a directory, e.g. ",(0,a.mdx)("inlineCode",{parentName:"p"},"db"),", to hold a file for each database configuration option.\nSince we are expecting to have multiple config groups, we will proactively move all the configuration files\ninto a ",(0,a.mdx)("inlineCode",{parentName:"p"},"conf")," directory."),(0,a.mdx)("div",{className:"row"},(0,a.mdx)("div",{className:"col col--4"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Directory layout"',title:'"Directory','layout"':!0},"\u251c\u2500 conf\n\u2502 \u2514\u2500 db\n\u2502 \u251c\u2500 mysql.yaml\n\u2502 \u2514\u2500 postgresql.yaml\n\u2514\u2500\u2500 my_app.py\n"))),(0,a.mdx)("div",{className:"col col--4"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml"',title:'"db/mysql.yaml"'},"driver: mysql\nuser: omry\npassword: secret\n\n\n"))),(0,a.mdx)("div",{className:"col col--4"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/postgresql.yaml"',title:'"db/postgresql.yaml"'},"driver: postgresql\nuser: postgres_user\npassword: drowssap\ntimeout: 10\n\n")))),(0,a.mdx)("h3",{id:"using-config-groups"},"Using config groups"),(0,a.mdx)("p",null,"Since we moved all the configs into the ",(0,a.mdx)("inlineCode",{parentName:"p"},"conf")," directory, we need to tell Hydra where to find them using the ",(0,a.mdx)("inlineCode",{parentName:"p"},"config_path")," parameter.\n",(0,a.mdx)("strong",{parentName:"p"},(0,a.mdx)("inlineCode",{parentName:"strong"},"config_path")," is a directory relative to ",(0,a.mdx)("inlineCode",{parentName:"strong"},"my_app.py")),"."),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app.py" {4}',title:'"my_app.py"',"{4}":!0},'from omegaconf import DictConfig, OmegaConf\nimport hydra\n\n@hydra.main(version_base=None, config_path="conf")\ndef my_app(cfg: DictConfig) -> None:\n print(OmegaConf.to_yaml(cfg))\n\nif __name__ == "__main__":\n my_app()\n')),(0,a.mdx)("p",null,"Running ",(0,a.mdx)("inlineCode",{parentName:"p"},"my_app.py")," without requesting a configuration will print an empty config."),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py\n{}\n")),(0,a.mdx)("p",null,"Select an item from a config group with ",(0,a.mdx)("inlineCode",{parentName:"p"},"+GROUP=OPTION"),", e.g: "),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{2}","{2}":!0},"$ python my_app.py +db=postgresql\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 10\n user: postgres_user\n")),(0,a.mdx)("p",null,"By default, the config group determines where the config content is placed inside the final config object.\nIn Hydra, the path to the config content is referred to as the config ",(0,a.mdx)("inlineCode",{parentName:"p"},"package"),".\nThe package of ",(0,a.mdx)("inlineCode",{parentName:"p"},"db/postgresql.yaml")," is ",(0,a.mdx)("inlineCode",{parentName:"p"},"db"),":"),(0,a.mdx)("p",null,"Like before, you can still override individual values in the resulting config:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py +db=postgresql db.timeout=20\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 20\n user: postgres_user\n")),(0,a.mdx)("h3",{id:"advanced-topics"},"Advanced topics"),(0,a.mdx)("ul",null,(0,a.mdx)("li",{parentName:"ul"},"Config content can be relocated via package overrides. See ",(0,a.mdx)("a",{parentName:"li",href:"/docs/1.3/advanced/overriding_packages"},"Reference Manual/Packages"),". "),(0,a.mdx)("li",{parentName:"ul"},"Multiple options can be selected from the same Config Group by specifying them as a list.",(0,a.mdx)("br",{parentName:"li"}),"See ",(0,a.mdx)("a",{parentName:"li",href:"/docs/1.3/patterns/select_multiple_configs_from_config_group"},"Common Patterns/Selecting multiple configs from a Config Group"))))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/10dd8346.9185de16.js b/assets/js/10dd8346.9185de16.js new file mode 100644 index 0000000000..a039f72e30 --- /dev/null +++ b/assets/js/10dd8346.9185de16.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3893],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>l,MDXProvider:()=>d,mdx:()=>f,useMDXComponents:()=>m,withMDXComponents:()=>c});var r=t(96540);function o(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function a(){return a=Object.assign||function(e){for(var n=1;n=0||(o[t]=e[t]);return o}(e,n);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(o[t]=e[t])}return o}var l=r.createContext({}),c=function(e){return function(n){var t=m(n.components);return r.createElement(e,a({},n,{components:t}))}},m=function(e){var n=r.useContext(l),t=n;return e&&(t="function"==typeof e?e(n):p(p({},n),e)),t},d=function(e){var n=m(e.components);return r.createElement(l.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},g=r.forwardRef((function(e,n){var t=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,l=s(e,["components","mdxType","originalType","parentName"]),c=m(t),d=o,g=c["".concat(i,".").concat(d)]||c[d]||u[d]||a;return t?r.createElement(g,p(p({ref:n},l),{},{components:t})):r.createElement(g,p({ref:n},l))}));function f(e,n){var t=arguments,o=n&&n.mdxType;if("string"==typeof e||o){var a=t.length,i=new Array(a);i[0]=g;var p={};for(var s in n)hasOwnProperty.call(n,s)&&(p[s]=n[s]);p.originalType=e,p.mdxType="string"==typeof e?e:o,i[1]=p;for(var l=2;l{t.d(n,{A:()=>s,C:()=>l});var r=t(58168),o=t(96540),a=t(75489),i=t(44586),p=t(74098);function s(e){return o.createElement(a.default,(0,r.A)({},e,{to:(n=e.to,s=(0,p.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==s?void 0:s.name)?t:"current"]+n),target:"_blank"}));var n,t,s}function l(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return o.createElement(s,e,o.createElement("span",null,"\xa0"),o.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},39390:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>l,default:()=>u,frontMatter:()=>s,metadata:()=>c,toc:()=>m});var r=t(58168),o=t(98587),a=(t(96540),t(15680)),i=t(49595),p=["components"],s={id:"config_groups",title:"Grouping config files"},l=void 0,c={unversionedId:"tutorials/basic/your_first_app/config_groups",id:"version-1.3/tutorials/basic/your_first_app/config_groups",title:"Grouping config files",description:"Suppose you want to benchmark your application on each of PostgreSQL and MySQL. To do this, use config groups.",source:"@site/versioned_docs/version-1.3/tutorials/basic/your_first_app/4_config_groups.md",sourceDirName:"tutorials/basic/your_first_app",slug:"/tutorials/basic/your_first_app/config_groups",permalink:"/docs/1.3/tutorials/basic/your_first_app/config_groups",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/tutorials/basic/your_first_app/4_config_groups.md",tags:[],version:"1.3",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:4,frontMatter:{id:"config_groups",title:"Grouping config files"},sidebar:"docs",previous:{title:"Using the config object",permalink:"/docs/1.3/tutorials/basic/your_first_app/using_config"},next:{title:"Selecting default configs",permalink:"/docs/1.3/tutorials/basic/your_first_app/defaults"}},m=[{value:"Creating config groups",id:"creating-config-groups",children:[],level:3},{value:"Using config groups",id:"using-config-groups",children:[],level:3},{value:"Advanced topics",id:"advanced-topics",children:[],level:3}],d={toc:m};function u(e){var n=e.components,t=(0,o.A)(e,p);return(0,a.mdx)("wrapper",(0,r.A)({},d,t,{components:n,mdxType:"MDXLayout"}),(0,a.mdx)(i.C,{to:"examples/tutorials/basic/your_first_hydra_app/4_config_groups",mdxType:"ExampleGithubLink"}),(0,a.mdx)("p",null,"Suppose you want to benchmark your application on each of PostgreSQL and MySQL. To do this, use config groups. "),(0,a.mdx)("p",null,"A ",(0,a.mdx)("em",{parentName:"p"},(0,a.mdx)("strong",{parentName:"em"},"Config Group"))," is a named group with a set of valid options.\nSelecting a non-existent config option generates an error message with the valid options."),(0,a.mdx)("h3",{id:"creating-config-groups"},"Creating config groups"),(0,a.mdx)("p",null,"To create a config group, create a directory, e.g. ",(0,a.mdx)("inlineCode",{parentName:"p"},"db"),", to hold a file for each database configuration option.\nSince we are expecting to have multiple config groups, we will proactively move all the configuration files\ninto a ",(0,a.mdx)("inlineCode",{parentName:"p"},"conf")," directory."),(0,a.mdx)("div",{className:"row"},(0,a.mdx)("div",{className:"col col--4"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Directory layout"',title:'"Directory','layout"':!0},"\u251c\u2500 conf\n\u2502 \u2514\u2500 db\n\u2502 \u251c\u2500 mysql.yaml\n\u2502 \u2514\u2500 postgresql.yaml\n\u2514\u2500\u2500 my_app.py\n"))),(0,a.mdx)("div",{className:"col col--4"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml"',title:'"db/mysql.yaml"'},"driver: mysql\nuser: omry\npassword: secret\n\n\n"))),(0,a.mdx)("div",{className:"col col--4"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/postgresql.yaml"',title:'"db/postgresql.yaml"'},"driver: postgresql\nuser: postgres_user\npassword: drowssap\ntimeout: 10\n\n")))),(0,a.mdx)("h3",{id:"using-config-groups"},"Using config groups"),(0,a.mdx)("p",null,"Since we moved all the configs into the ",(0,a.mdx)("inlineCode",{parentName:"p"},"conf")," directory, we need to tell Hydra where to find them using the ",(0,a.mdx)("inlineCode",{parentName:"p"},"config_path")," parameter.\n",(0,a.mdx)("strong",{parentName:"p"},(0,a.mdx)("inlineCode",{parentName:"strong"},"config_path")," is a directory relative to ",(0,a.mdx)("inlineCode",{parentName:"strong"},"my_app.py")),"."),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app.py" {4}',title:'"my_app.py"',"{4}":!0},'from omegaconf import DictConfig, OmegaConf\nimport hydra\n\n@hydra.main(version_base=None, config_path="conf")\ndef my_app(cfg: DictConfig) -> None:\n print(OmegaConf.to_yaml(cfg))\n\nif __name__ == "__main__":\n my_app()\n')),(0,a.mdx)("p",null,"Running ",(0,a.mdx)("inlineCode",{parentName:"p"},"my_app.py")," without requesting a configuration will print an empty config."),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py\n{}\n")),(0,a.mdx)("p",null,"Select an item from a config group with ",(0,a.mdx)("inlineCode",{parentName:"p"},"+GROUP=OPTION"),", e.g: "),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{2}","{2}":!0},"$ python my_app.py +db=postgresql\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 10\n user: postgres_user\n")),(0,a.mdx)("p",null,"By default, the config group determines where the config content is placed inside the final config object.\nIn Hydra, the path to the config content is referred to as the config ",(0,a.mdx)("inlineCode",{parentName:"p"},"package"),".\nThe package of ",(0,a.mdx)("inlineCode",{parentName:"p"},"db/postgresql.yaml")," is ",(0,a.mdx)("inlineCode",{parentName:"p"},"db"),":"),(0,a.mdx)("p",null,"Like before, you can still override individual values in the resulting config:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py +db=postgresql db.timeout=20\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 20\n user: postgres_user\n")),(0,a.mdx)("h3",{id:"advanced-topics"},"Advanced topics"),(0,a.mdx)("ul",null,(0,a.mdx)("li",{parentName:"ul"},"Config content can be relocated via package overrides. See ",(0,a.mdx)("a",{parentName:"li",href:"/docs/1.3/advanced/overriding_packages"},"Reference Manual/Packages"),". "),(0,a.mdx)("li",{parentName:"ul"},"Multiple options can be selected from the same Config Group by specifying them as a list.",(0,a.mdx)("br",{parentName:"li"}),"See ",(0,a.mdx)("a",{parentName:"li",href:"/docs/1.3/patterns/select_multiple_configs_from_config_group"},"Common Patterns/Selecting multiple configs from a Config Group"))))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/10e059cb.312176c3.js b/assets/js/10e059cb.312176c3.js new file mode 100644 index 0000000000..ad2a43a2c4 --- /dev/null +++ b/assets/js/10e059cb.312176c3.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[9310],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>s,MDXProvider:()=>c,mdx:()=>g,useMDXComponents:()=>p,withMDXComponents:()=>m});var t=a(96540);function i(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function r(){return r=Object.assign||function(e){for(var n=1;n=0||(i[a]=e[a]);return i}(e,n);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(i[a]=e[a])}return i}var s=t.createContext({}),m=function(e){return function(n){var a=p(n.components);return t.createElement(e,r({},n,{components:a}))}},p=function(e){var n=t.useContext(s),a=n;return e&&(a="function"==typeof e?e(n):o(o({},n),e)),a},c=function(e){var n=p(e.components);return t.createElement(s.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return t.createElement(t.Fragment,{},n)}},h=t.forwardRef((function(e,n){var a=e.components,i=e.mdxType,r=e.originalType,l=e.parentName,s=d(e,["components","mdxType","originalType","parentName"]),m=p(a),c=i,h=m["".concat(l,".").concat(c)]||m[c]||u[c]||r;return a?t.createElement(h,o(o({ref:n},s),{},{components:a})):t.createElement(h,o({ref:n},s))}));function g(e,n){var a=arguments,i=n&&n.mdxType;if("string"==typeof e||i){var r=a.length,l=new Array(r);l[0]=h;var o={};for(var d in n)hasOwnProperty.call(n,d)&&(o[d]=n[d]);o.originalType=e,o.mdxType="string"==typeof e?e:i,l[1]=o;for(var s=2;s{a.d(n,{A:()=>d,C:()=>s});var t=a(58168),i=a(96540),r=a(75489),l=a(44586),o=a(74098);function d(e){return i.createElement(r.default,(0,t.A)({},e,{to:(n=e.to,d=(0,o.useActiveVersion)(),(0,l.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(a=null==d?void 0:d.name)?a:"current"]+n),target:"_blank"}));var n,a,d}function s(e){var n,a=null!=(n=e.text)?n:"Example (Click Here)";return i.createElement(d,e,i.createElement("span",null,"\xa0"),i.createElement("img",{src:"https://img.shields.io/badge/-"+a+"-informational",alt:"Example (Click Here)"}))}},82622:(e,n,a)=>{a.r(n),a.d(n,{contentTitle:()=>s,default:()=>u,frontMatter:()=>d,metadata:()=>m,toc:()=>p});var t=a(58168),i=a(98587),r=(a(96540),a(15680)),l=a(49595),o=["components"],d={id:"basic",hide_title:!0,sidebar_label:"Basic Override syntax"},s=void 0,m={unversionedId:"advanced/override_grammar/basic",id:"advanced/override_grammar/basic",title:"basic",description:"Basic Override syntax",source:"@site/docs/advanced/override_grammar/basic.md",sourceDirName:"advanced/override_grammar",slug:"/advanced/override_grammar/basic",permalink:"/docs/advanced/override_grammar/basic",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/advanced/override_grammar/basic.md",tags:[],version:"current",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"basic",hide_title:!0,sidebar_label:"Basic Override syntax"},sidebar:"docs",previous:{title:"Hydra's command line flags",permalink:"/docs/advanced/hydra-command-line-flags"},next:{title:"Extended Override syntax",permalink:"/docs/advanced/override_grammar/extended"}},p=[{value:"Basic Override syntax",id:"basic-override-syntax",children:[],level:2},{value:"Basic examples",id:"basic-examples",children:[{value:"Modifying the Config Object",id:"modifying-the-config-object",children:[],level:3},{value:"Modifying the Defaults List",id:"modifying-the-defaults-list",children:[],level:3}],level:2},{value:"Grammar",id:"grammar",children:[],level:2},{value:"Elements",id:"elements",children:[{value:"Key",id:"key",children:[],level:3},{value:"Quoted values",id:"quoted-values",children:[],level:3},{value:"Whitespaces in unquoted values",id:"whitespaces-in-unquoted-values",children:[],level:3},{value:"Escaped characters in unquoted values",id:"escaped-characters-in-unquoted-values",children:[],level:3},{value:"Primitives",id:"primitives",children:[],level:3}],level:2},{value:"Dictionaries and Lists",id:"dictionaries-and-lists",children:[{value:"Lists",id:"lists",children:[],level:3},{value:"Dictionaries",id:"dictionaries",children:[],level:3},{value:"Sweeper syntax",id:"sweeper-syntax",children:[],level:3},{value:"Functions",id:"functions",children:[],level:3}],level:2},{value:"Working with your shell",id:"working-with-your-shell",children:[{value:"Bash",id:"bash",children:[],level:3},{value:"Other shells",id:"other-shells",children:[],level:3}],level:2}],c={toc:p};function u(e){var n=e.components,a=(0,i.A)(e,o);return(0,r.mdx)("wrapper",(0,t.A)({},c,a,{components:n,mdxType:"MDXLayout"}),(0,r.mdx)("h2",{id:"basic-override-syntax"},"Basic Override syntax"),(0,r.mdx)("p",null,"You can manipulate your configuration with overrides (via the command line or the Compose API). This includes:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Modifying the ",(0,r.mdx)("inlineCode",{parentName:"li"},"Defaults List")),(0,r.mdx)("li",{parentName:"ul"},"Modifying the config object")),(0,r.mdx)("p",null,"Overrides matching a config group are modifying the ",(0,r.mdx)("inlineCode",{parentName:"p"},"Defaults List"),";\nThe rest are manipulating the config object."),(0,r.mdx)("h2",{id:"basic-examples"},"Basic examples"),(0,r.mdx)("h3",{id:"modifying-the-config-object"},"Modifying the Config Object"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Overriding a config value : ",(0,r.mdx)("inlineCode",{parentName:"li"},"foo.bar=value")),(0,r.mdx)("li",{parentName:"ul"},"Appending a config value : ",(0,r.mdx)("inlineCode",{parentName:"li"},"+foo.bar=value")),(0,r.mdx)("li",{parentName:"ul"},"Appending or overriding a config value : ",(0,r.mdx)("inlineCode",{parentName:"li"},"++foo.bar=value")),(0,r.mdx)("li",{parentName:"ul"},"Removing a config value : ",(0,r.mdx)("inlineCode",{parentName:"li"},"~foo.bar"),", ",(0,r.mdx)("inlineCode",{parentName:"li"},"~foo.bar=value"))),(0,r.mdx)("h3",{id:"modifying-the-defaults-list"},"Modifying the Defaults List"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Overriding selected Option: ",(0,r.mdx)("inlineCode",{parentName:"li"},"db=mysql"),", ",(0,r.mdx)("inlineCode",{parentName:"li"},"server/db=mysql")),(0,r.mdx)("li",{parentName:"ul"},"Appending to Defaults List: ",(0,r.mdx)("inlineCode",{parentName:"li"},"+db=mysql"),", ",(0,r.mdx)("inlineCode",{parentName:"li"},"+server/db=mysql")),(0,r.mdx)("li",{parentName:"ul"},"Deleting from Defaults List: ",(0,r.mdx)("inlineCode",{parentName:"li"},"~db"),", ",(0,r.mdx)("inlineCode",{parentName:"li"},"~db=mysql"),", ",(0,r.mdx)("inlineCode",{parentName:"li"},"~server/db"),", ",(0,r.mdx)("inlineCode",{parentName:"li"},"~server/db=mysql"))),(0,r.mdx)("h2",{id:"grammar"},"Grammar"),(0,r.mdx)("p",null,"Hydra supports a rich ",(0,r.mdx)("a",{parentName:"p",href:"https://en.wikipedia.org/wiki/Domain-specific_language"},"DSL")," in the command line.\nBelow are the parser rules from grammar. You can see the full ",(0,r.mdx)(l.A,{to:"hydra/grammar/OverrideLexer.g4",mdxType:"GithubLink"},"Lexer")," and ",(0,r.mdx)(l.A,{to:"hydra/grammar/OverrideParser.g4",mdxType:"GithubLink"},"Parser")," definitions on GitHub."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-antlr4",metastring:'title="OverrideParser.g4"',title:'"OverrideParser.g4"'},"// High-level command-line override.\n\noverride: (\n key EQUAL value? // key=value, key= (for empty value)\n | TILDE key (EQUAL value?)? // ~key | ~key=value\n | PLUS PLUS? key EQUAL value? // +key= | +key=value | ++key=value\n) EOF;\n\n// Key:\nkey : packageOrGroup (AT package)?; // key | group@pkg\n\npackageOrGroup: package | ID (SLASH ID)+; // db, hydra/launcher\npackage: ( | ID | KEY_SPECIAL | DOT_PATH); // db, $db, hydra.launcher, or the empty (for _global_ package)\n\n// Elements (that may be swept over).\n\nvalue: element | simpleChoiceSweep;\n\nelement:\n primitive\n | listContainer\n | dictContainer\n | function\n;\n\nsimpleChoiceSweep:\n element (COMMA element)+ // value1,value2,value3\n;\n\n// Functions.\n\nargName: ID EQUAL;\nfunction: ID POPEN (argName? element (COMMA argName? element )* )? PCLOSE;\n\n// Data structures.\n\nlistContainer: BRACKET_OPEN // [], [1,2,3], [a,b,[1,2]]\n (element(COMMA element)*)?\nBRACKET_CLOSE;\n\ndictContainer: BRACE_OPEN (dictKeyValuePair (COMMA dictKeyValuePair)*)? BRACE_CLOSE; // {}, {a:10,b:20}\ndictKeyValuePair: dictKey COLON element;\n\n// Primitive types.\n\nprimitive:\n QUOTED_VALUE // 'hello world', \"hello world\"\n | ( ID // foo-bar_10\n | NULL // null, NULL\n | INT // 0, 10, -20, 1_000_000\n | FLOAT // 3.14, -20.0, 1e-1, -10e3\n | BOOL // true, TrUe, false, False\n | INTERPOLATION // ${foo.bar}, ${oc.env:USER,me}\n | UNQUOTED_CHAR // /, -, \\, +, ., $, %, *, @, ?, |\n | COLON // :\n | ESC // \\\\, \\(, \\), \\[, \\], \\{, \\}, \\:, \\=, \\ , \\\\t, \\,\n | WS // whitespaces\n )+;\n\n// Same as `primitive` except that `COLON` and `INTERPOLATION` are not allowed.\ndictKey:\n ( ID // foo-bar_10\n | NULL // null, NULL\n | INT // 0, 10, -20, 1_000_000\n | FLOAT // 3.14, -20.0, 1e-1, -10e3\n | BOOL // true, TrUe, false, False\n | UNQUOTED_CHAR // /, -, \\, +, ., $, %, *, @, ?, |\n | ESC // \\\\, \\(, \\), \\[, \\], \\{, \\}, \\:, \\=, \\ , \\\\t, \\,\n | WS // whitespaces\n )+;\n")),(0,r.mdx)("h2",{id:"elements"},"Elements"),(0,r.mdx)("h3",{id:"key"},"Key"),(0,r.mdx)("p",null,"Key is the component before the =. A few examples:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-shell",metastring:"script",script:!0},"foo.bar # A config key\nhydra/launcher # A config group\ngroup@pkg # A config group assigned to the package pkg\ngroup@pkg1:pkg2 # A config group changing the package from pkg1 to pkg2\n")),(0,r.mdx)("h3",{id:"quoted-values"},"Quoted values"),(0,r.mdx)("p",null,"Hydra supports both double quotes and single quoted values.\nQuoted strings can accept any value between the quotes, but some characters need escaping:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"to include a single quote in a single quoted string, use ",(0,r.mdx)("inlineCode",{parentName:"li"},"\\'")," (for double quotes in a double quoted string, use ",(0,r.mdx)("inlineCode",{parentName:"li"},'\\"'),")"),(0,r.mdx)("li",{parentName:"ul"},"any sequence of ",(0,r.mdx)("inlineCode",{parentName:"li"},"\\")," characters preceding a quote (either an escaped quote as described in the previous point, or the closing quote)\nmust be escaped by doubling the number of ",(0,r.mdx)("inlineCode",{parentName:"li"},"\\"))),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Double quotes"',title:'"Double','quotes"':!0},'"hello there"\n"escaped \\"double quote\\""\n"the path is C:\\\\\\"some folder\\"\\\\"\n"1,2,3"\n"{a:10} ${xyz}"\n"\'single quoted string\'"\n'))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Single quotes"',title:'"Single','quotes"':!0},"'hello there'\n'escaped \\'single quote\\''\n'the path is C:\\\\\\'some folder\\'\\\\'\n'1,2,3'\n'{a:10} ${xyz}'\n'\"double quoted string\"'\n")))),(0,r.mdx)("p",null,"It may be necessary to use multiple pairs of quotes to prevent your\nshell from consuming quotation marks before they are passed to hydra."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-shell"},"$ python my_app.py '+foo=\"{a: 10}\"'\nfoo: '{a: 10}'\n\n$ python my_app.py '+foo={a: 10}'\nfoo:\n a: 10\n\n")),(0,r.mdx)("p",null,"Here are some best practices around quoting in CLI overrides:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Quote the whole key=value pair with single quotes, as in the first two\nexamples above. These quotes are for the benefit of the shell."),(0,r.mdx)("li",{parentName:"ul"},"Do not quote keys."),(0,r.mdx)("li",{parentName:"ul"},"Only quote values if they contain a space. It will work if you always quote\nvalues, but it will turn numbers/dicts/lists into strings (as in the first\nexample above)."),(0,r.mdx)("li",{parentName:"ul"},"When you are quoting values, use double quotes to avoid collision with the\nouter single quoted consumed by the shell.")),(0,r.mdx)("h3",{id:"whitespaces-in-unquoted-values"},"Whitespaces in unquoted values"),(0,r.mdx)("p",null,"Unquoted Override values can contain non leading or trailing whitespaces.\nFor example, ",(0,r.mdx)("inlineCode",{parentName:"p"},"msg=hello world")," is a legal override (key is ",(0,r.mdx)("inlineCode",{parentName:"p"},"msg")," and value is the string ",(0,r.mdx)("inlineCode",{parentName:"p"},"hello world"),").\nNormally, your shell will interpret values with whitespaces as being multiple parameters (",(0,r.mdx)("inlineCode",{parentName:"p"},"key=a b")," would be interpreted as ",(0,r.mdx)("inlineCode",{parentName:"p"},"key=a")," and ",(0,r.mdx)("inlineCode",{parentName:"p"},"b"),").\nTo prevent this you can quote them with a single quote. For example:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-shell"},"$ python my_app.py 'msg=hello world'\n")),(0,r.mdx)("p",null,"Note that trailing and leading whitespace are ignored, the above is equivalent to:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-shell"},"$ python my_app.py 'msg= hello world '\n")),(0,r.mdx)("h3",{id:"escaped-characters-in-unquoted-values"},"Escaped characters in unquoted values"),(0,r.mdx)("p",null,"Hydra's parser considers some characters to be illegal in unquoted strings.\nThese otherwise special characters may be included in unquoted values by escaping them with a ",(0,r.mdx)("inlineCode",{parentName:"p"},"\\"),".\nThese characters are: ",(0,r.mdx)("inlineCode",{parentName:"p"},"\\()[]{}:=, \\t")," (the last two ones being the whitespace and tab characters)."),(0,r.mdx)("p",null,"As an example, in the following ",(0,r.mdx)("inlineCode",{parentName:"p"},"dir")," is set to the string ",(0,r.mdx)("inlineCode",{parentName:"p"},"job{a=1,b=2,c=3}"),":"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-shell"},"$ python my_app.py 'dir=job\\{a\\=1\\,b\\=2\\,c\\=3\\}'\n")),(0,r.mdx)("p",null,"As an alternative to escaping special characters with a backslash, the value containing the special character may be quoted:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-shell"},"$ python my_app.py 'dir=A[B' # parser error\n$ python my_app.py 'dir=\"A[B\"' # ok\n$ python my_app.py 'dir=A\\[B' # ok\n")),(0,r.mdx)("h3",{id:"primitives"},"Primitives"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"id")," : oompa10, loompa_12"),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"null"),": null"),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"int"),": 10, -20, 0, 1_000_000."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"float"),": 3.14, -10e6, inf, -inf, nan."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"bool"),": true, false"),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"dot_path"),": foo.bar"),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"interpolation"),": ${foo.bar}, ${oc.env:USER,me}")),(0,r.mdx)("p",null,"Constants (null, true, false, inf, nan) are case-insensitive."),(0,r.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,r.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,r.mdx)("h5",{parentName:"div"},(0,r.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,r.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,r.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,r.mdx)("div",{parentName:"div",className:"admonition-content"},(0,r.mdx)("p",{parentName:"div"},"Always single-quote interpolations in the shell, to prevent replacement with shell variables:"),(0,r.mdx)("pre",{parentName:"div"},(0,r.mdx)("code",{parentName:"pre",className:"language-shell"},"$ python my_app.py 'dir=/root/${name}'\n")),(0,r.mdx)("p",{parentName:"div"},"In addition, more complex interpolations containing special characters may require being passed within a quoted value\n(note the extra double quotes surrounding the interpolation):"),(0,r.mdx)("pre",{parentName:"div"},(0,r.mdx)("code",{parentName:"pre",className:"language-shell"},"$ python my_app.py 'dir=\"${get_dir: {root: /root, name: ${name}}}\"'\n")))),(0,r.mdx)("h2",{id:"dictionaries-and-lists"},"Dictionaries and Lists"),(0,r.mdx)("h3",{id:"lists"},"Lists"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},"foo=[1,2,3]\nnested=[a,[b,[c]]]\n")),(0,r.mdx)("h3",{id:"dictionaries"},"Dictionaries"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},"foo={a:10,b:20}\nnested={a:10,b:{c:30,d:40}}\n")),(0,r.mdx)("p",null,"Dictionaries are merged, not assigned. The following example illustrates the point:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Input config"',title:'"Input','config"':!0},"db:\n driver: mysql\n user: ???\n pass: ???\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db={user:root,pass:1234}"',title:'"db'},"db:\n driver: mysql\n user: root\n pass: 1234\n")))),(0,r.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,r.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,r.mdx)("h5",{parentName:"div"},(0,r.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,r.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,r.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,r.mdx)("div",{parentName:"div",className:"admonition-content"},(0,r.mdx)("p",{parentName:"div"},"Always single-quote overrides that contains dicts and lists in the shell."))),(0,r.mdx)("h3",{id:"sweeper-syntax"},"Sweeper syntax"),(0,r.mdx)("p",null,"A choice sweep is comma separated list with two or more elements:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-shell",metastring:"script",script:!0},'key=a,b # Simple sweep: ChoiceSweep(a, b)\nkey="a,b","c,d" # Elements can be quoted strings, ChoiceSweep("a,b", "c,d")\nkey=[a,b],[c,d] # Elements can be real lists, ChoiceSweep([a,b], [c,d])\nkey={a:10, b:20},{c:30,d:40} # And dictionaries: ChoiceSweep({a:10, b:20}, {c:30,d:40})\n')),(0,r.mdx)("p",null,"More sweeping options are described in the ",(0,r.mdx)("a",{parentName:"p",href:"/docs/advanced/override_grammar/extended"},"Extended Grammar page"),"."),(0,r.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,r.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,r.mdx)("h5",{parentName:"div"},(0,r.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,r.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,r.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,r.mdx)("div",{parentName:"div",className:"admonition-content"},(0,r.mdx)("p",{parentName:"div"},"You may need to quote your choice sweep in the shell."))),(0,r.mdx)("h3",{id:"functions"},"Functions"),(0,r.mdx)("p",null,"Hydra supports several functions in the command line.\nSee the ",(0,r.mdx)("a",{parentName:"p",href:"/docs/advanced/override_grammar/extended"},"Extended Grammar page")," for more information."),(0,r.mdx)("h2",{id:"working-with-your-shell"},"Working with your shell"),(0,r.mdx)("p",null,"All shells interprets command line inputs and may change what is passed to the process.\nA good way to determine what the shell is doing to your command is to ",(0,r.mdx)("inlineCode",{parentName:"p"},"echo")," it."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-shell",metastring:"script",script:!0},"# bash output\n$ echo foo_{a:10,b:20} ${HOME} [b,c]*\nfoo_a:10 foo_b:20 /home/omry build_helpers\n$ echo 'foo_{a:10,b:20}' '${HOME}' '[b,c]*'\nfoo_{a:10,b:20} ${HOME} [b,c]*\n")),(0,r.mdx)("p",null,"If in doubt, quote a command line element with a ",(0,r.mdx)("strong",{parentName:"p"},"single quote")," (",(0,r.mdx)("inlineCode",{parentName:"p"},"'"),")."),(0,r.mdx)("p",null,"If you want to pass quotes to Hydra in a shell quoted string, it's best to pass double quotes."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-shell",metastring:"script",script:!0},'$ echo \'"hello world"\'\n"hello world"\n')),(0,r.mdx)("p",null,"You can use some shell specific commands to change their behavior, but the cost will be that their behavior will change."),(0,r.mdx)("h3",{id:"bash"},"Bash"),(0,r.mdx)("p",null,"You can disable braces expansion, filename generation (globing) and hist expansion. Please note that this will change\nyour shell behavior for the current session."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-shell",metastring:"script",script:!0},"$ set +o braceexpand -o noglob +o histexpand\n$ echo key1={a:10,b:20} key2=${HOME} key=[b]*\nkey1={a:10,b:20} key2=/home/omry key=[b]*\n# does not help with () though:\n$ echo key=choice(a,b,c)\nbash: syntax error near unexpected token '('\n$ echo 'key=choice(a,b,c)'\nkey=choice(a,b,c)\n")),(0,r.mdx)("h3",{id:"other-shells"},"Other shells"),(0,r.mdx)("p",null,"Send a PR to add information about your favorite shell here."))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/10e059cb.59ef720d.js b/assets/js/10e059cb.59ef720d.js deleted file mode 100644 index 4e26cd5d08..0000000000 --- a/assets/js/10e059cb.59ef720d.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[9310],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>s,MDXProvider:()=>c,mdx:()=>g,useMDXComponents:()=>p,withMDXComponents:()=>m});var t=a(96540);function i(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function r(){return r=Object.assign||function(e){for(var n=1;n=0||(i[a]=e[a]);return i}(e,n);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(i[a]=e[a])}return i}var s=t.createContext({}),m=function(e){return function(n){var a=p(n.components);return t.createElement(e,r({},n,{components:a}))}},p=function(e){var n=t.useContext(s),a=n;return e&&(a="function"==typeof e?e(n):o(o({},n),e)),a},c=function(e){var n=p(e.components);return t.createElement(s.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return t.createElement(t.Fragment,{},n)}},h=t.forwardRef((function(e,n){var a=e.components,i=e.mdxType,r=e.originalType,l=e.parentName,s=d(e,["components","mdxType","originalType","parentName"]),m=p(a),c=i,h=m["".concat(l,".").concat(c)]||m[c]||u[c]||r;return a?t.createElement(h,o(o({ref:n},s),{},{components:a})):t.createElement(h,o({ref:n},s))}));function g(e,n){var a=arguments,i=n&&n.mdxType;if("string"==typeof e||i){var r=a.length,l=new Array(r);l[0]=h;var o={};for(var d in n)hasOwnProperty.call(n,d)&&(o[d]=n[d]);o.originalType=e,o.mdxType="string"==typeof e?e:i,l[1]=o;for(var s=2;s{a.d(n,{A:()=>d,C:()=>s});var t=a(58168),i=a(96540),r=a(75489),l=a(44586),o=a(74098);function d(e){return i.createElement(r.default,(0,t.A)({},e,{to:(n=e.to,d=(0,o.useActiveVersion)(),(0,l.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(a=null==d?void 0:d.name)?a:"current"]+n),target:"_blank"}));var n,a,d}function s(e){var n,a=null!=(n=e.text)?n:"Example (Click Here)";return i.createElement(d,e,i.createElement("span",null,"\xa0"),i.createElement("img",{src:"https://img.shields.io/badge/-"+a+"-informational",alt:"Example (Click Here)"}))}},82622:(e,n,a)=>{a.r(n),a.d(n,{contentTitle:()=>s,default:()=>u,frontMatter:()=>d,metadata:()=>m,toc:()=>p});var t=a(58168),i=a(98587),r=(a(96540),a(15680)),l=a(49595),o=["components"],d={id:"basic",hide_title:!0,sidebar_label:"Basic Override syntax"},s=void 0,m={unversionedId:"advanced/override_grammar/basic",id:"advanced/override_grammar/basic",title:"basic",description:"Basic Override syntax",source:"@site/docs/advanced/override_grammar/basic.md",sourceDirName:"advanced/override_grammar",slug:"/advanced/override_grammar/basic",permalink:"/docs/advanced/override_grammar/basic",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/advanced/override_grammar/basic.md",tags:[],version:"current",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"basic",hide_title:!0,sidebar_label:"Basic Override syntax"},sidebar:"docs",previous:{title:"Hydra's command line flags",permalink:"/docs/advanced/hydra-command-line-flags"},next:{title:"Extended Override syntax",permalink:"/docs/advanced/override_grammar/extended"}},p=[{value:"Basic Override syntax",id:"basic-override-syntax",children:[],level:2},{value:"Basic examples",id:"basic-examples",children:[{value:"Modifying the Config Object",id:"modifying-the-config-object",children:[],level:3},{value:"Modifying the Defaults List",id:"modifying-the-defaults-list",children:[],level:3}],level:2},{value:"Grammar",id:"grammar",children:[],level:2},{value:"Elements",id:"elements",children:[{value:"Key",id:"key",children:[],level:3},{value:"Quoted values",id:"quoted-values",children:[],level:3},{value:"Whitespaces in unquoted values",id:"whitespaces-in-unquoted-values",children:[],level:3},{value:"Escaped characters in unquoted values",id:"escaped-characters-in-unquoted-values",children:[],level:3},{value:"Primitives",id:"primitives",children:[],level:3}],level:2},{value:"Dictionaries and Lists",id:"dictionaries-and-lists",children:[{value:"Lists",id:"lists",children:[],level:3},{value:"Dictionaries",id:"dictionaries",children:[],level:3},{value:"Sweeper syntax",id:"sweeper-syntax",children:[],level:3},{value:"Functions",id:"functions",children:[],level:3}],level:2},{value:"Working with your shell",id:"working-with-your-shell",children:[{value:"Bash",id:"bash",children:[],level:3},{value:"Other shells",id:"other-shells",children:[],level:3}],level:2}],c={toc:p};function u(e){var n=e.components,a=(0,i.A)(e,o);return(0,r.mdx)("wrapper",(0,t.A)({},c,a,{components:n,mdxType:"MDXLayout"}),(0,r.mdx)("h2",{id:"basic-override-syntax"},"Basic Override syntax"),(0,r.mdx)("p",null,"You can manipulate your configuration with overrides (via the command line or the Compose API). This includes:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Modifying the ",(0,r.mdx)("inlineCode",{parentName:"li"},"Defaults List")),(0,r.mdx)("li",{parentName:"ul"},"Modifying the config object")),(0,r.mdx)("p",null,"Overrides matching a config group are modifying the ",(0,r.mdx)("inlineCode",{parentName:"p"},"Defaults List"),";\nThe rest are manipulating the config object."),(0,r.mdx)("h2",{id:"basic-examples"},"Basic examples"),(0,r.mdx)("h3",{id:"modifying-the-config-object"},"Modifying the Config Object"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Overriding a config value : ",(0,r.mdx)("inlineCode",{parentName:"li"},"foo.bar=value")),(0,r.mdx)("li",{parentName:"ul"},"Appending a config value : ",(0,r.mdx)("inlineCode",{parentName:"li"},"+foo.bar=value")),(0,r.mdx)("li",{parentName:"ul"},"Appending or overriding a config value : ",(0,r.mdx)("inlineCode",{parentName:"li"},"++foo.bar=value")),(0,r.mdx)("li",{parentName:"ul"},"Removing a config value : ",(0,r.mdx)("inlineCode",{parentName:"li"},"~foo.bar"),", ",(0,r.mdx)("inlineCode",{parentName:"li"},"~foo.bar=value"))),(0,r.mdx)("h3",{id:"modifying-the-defaults-list"},"Modifying the Defaults List"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Overriding selected Option: ",(0,r.mdx)("inlineCode",{parentName:"li"},"db=mysql"),", ",(0,r.mdx)("inlineCode",{parentName:"li"},"server/db=mysql")),(0,r.mdx)("li",{parentName:"ul"},"Appending to Defaults List: ",(0,r.mdx)("inlineCode",{parentName:"li"},"+db=mysql"),", ",(0,r.mdx)("inlineCode",{parentName:"li"},"+server/db=mysql")),(0,r.mdx)("li",{parentName:"ul"},"Deleting from Defaults List: ",(0,r.mdx)("inlineCode",{parentName:"li"},"~db"),", ",(0,r.mdx)("inlineCode",{parentName:"li"},"~db=mysql"),", ",(0,r.mdx)("inlineCode",{parentName:"li"},"~server/db"),", ",(0,r.mdx)("inlineCode",{parentName:"li"},"~server/db=mysql"))),(0,r.mdx)("h2",{id:"grammar"},"Grammar"),(0,r.mdx)("p",null,"Hydra supports a rich ",(0,r.mdx)("a",{parentName:"p",href:"https://en.wikipedia.org/wiki/Domain-specific_language"},"DSL")," in the command line.\nBelow are the parser rules from grammar. You can see the full ",(0,r.mdx)(l.A,{to:"hydra/grammar/OverrideLexer.g4",mdxType:"GithubLink"},"Lexer")," and ",(0,r.mdx)(l.A,{to:"hydra/grammar/OverrideParser.g4",mdxType:"GithubLink"},"Parser")," definitions on GitHub."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-antlr4",metastring:'title="OverrideParser.g4"',title:'"OverrideParser.g4"'},"// High-level command-line override.\n\noverride: (\n key EQUAL value? // key=value, key= (for empty value)\n | TILDE key (EQUAL value?)? // ~key | ~key=value\n | PLUS PLUS? key EQUAL value? // +key= | +key=value | ++key=value\n) EOF;\n\n// Key:\nkey : packageOrGroup (AT package)?; // key | group@pkg\n\npackageOrGroup: package | ID (SLASH ID)+; // db, hydra/launcher\npackage: ( | ID | KEY_SPECIAL | DOT_PATH); // db, $db, hydra.launcher, or the empty (for _global_ package)\n\n// Elements (that may be swept over).\n\nvalue: element | simpleChoiceSweep;\n\nelement:\n primitive\n | listContainer\n | dictContainer\n | function\n;\n\nsimpleChoiceSweep:\n element (COMMA element)+ // value1,value2,value3\n;\n\n// Functions.\n\nargName: ID EQUAL;\nfunction: ID POPEN (argName? element (COMMA argName? element )* )? PCLOSE;\n\n// Data structures.\n\nlistContainer: BRACKET_OPEN // [], [1,2,3], [a,b,[1,2]]\n (element(COMMA element)*)?\nBRACKET_CLOSE;\n\ndictContainer: BRACE_OPEN (dictKeyValuePair (COMMA dictKeyValuePair)*)? BRACE_CLOSE; // {}, {a:10,b:20}\ndictKeyValuePair: dictKey COLON element;\n\n// Primitive types.\n\nprimitive:\n QUOTED_VALUE // 'hello world', \"hello world\"\n | ( ID // foo-bar_10\n | NULL // null, NULL\n | INT // 0, 10, -20, 1_000_000\n | FLOAT // 3.14, -20.0, 1e-1, -10e3\n | BOOL // true, TrUe, false, False\n | INTERPOLATION // ${foo.bar}, ${oc.env:USER,me}\n | UNQUOTED_CHAR // /, -, \\, +, ., $, %, *, @, ?, |\n | COLON // :\n | ESC // \\\\, \\(, \\), \\[, \\], \\{, \\}, \\:, \\=, \\ , \\\\t, \\,\n | WS // whitespaces\n )+;\n\n// Same as `primitive` except that `COLON` and `INTERPOLATION` are not allowed.\ndictKey:\n ( ID // foo-bar_10\n | NULL // null, NULL\n | INT // 0, 10, -20, 1_000_000\n | FLOAT // 3.14, -20.0, 1e-1, -10e3\n | BOOL // true, TrUe, false, False\n | UNQUOTED_CHAR // /, -, \\, +, ., $, %, *, @, ?, |\n | ESC // \\\\, \\(, \\), \\[, \\], \\{, \\}, \\:, \\=, \\ , \\\\t, \\,\n | WS // whitespaces\n )+;\n")),(0,r.mdx)("h2",{id:"elements"},"Elements"),(0,r.mdx)("h3",{id:"key"},"Key"),(0,r.mdx)("p",null,"Key is the component before the =. A few examples:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-shell",metastring:"script",script:!0},"foo.bar # A config key\nhydra/launcher # A config group\ngroup@pkg # A config group assigned to the package pkg\ngroup@pkg1:pkg2 # A config group changing the package from pkg1 to pkg2\n")),(0,r.mdx)("h3",{id:"quoted-values"},"Quoted values"),(0,r.mdx)("p",null,"Hydra supports both double quotes and single quoted values.\nQuoted strings can accept any value between the quotes, but some characters need escaping:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"to include a single quote in a single quoted string, use ",(0,r.mdx)("inlineCode",{parentName:"li"},"\\'")," (for double quotes in a double quoted string, use ",(0,r.mdx)("inlineCode",{parentName:"li"},'\\"'),")"),(0,r.mdx)("li",{parentName:"ul"},"any sequence of ",(0,r.mdx)("inlineCode",{parentName:"li"},"\\")," characters preceding a quote (either an escaped quote as described in the previous point, or the closing quote)\nmust be escaped by doubling the number of ",(0,r.mdx)("inlineCode",{parentName:"li"},"\\"))),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Double quotes"',title:'"Double','quotes"':!0},'"hello there"\n"escaped \\"double quote\\""\n"the path is C:\\\\\\"some folder\\"\\\\"\n"1,2,3"\n"{a:10} ${xyz}"\n"\'single quoted string\'"\n'))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Single quotes"',title:'"Single','quotes"':!0},"'hello there'\n'escaped \\'single quote\\''\n'the path is C:\\\\\\'some folder\\'\\\\'\n'1,2,3'\n'{a:10} ${xyz}'\n'\"double quoted string\"'\n")))),(0,r.mdx)("p",null,"It may be necessary to use multiple pairs of quotes to prevent your\nshell from consuming quotation marks before they are passed to hydra."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-shell"},"$ python my_app.py '+foo=\"{a: 10}\"'\nfoo: '{a: 10}'\n\n$ python my_app.py '+foo={a: 10}'\nfoo:\n a: 10\n\n")),(0,r.mdx)("p",null,"Here are some best practices around quoting in CLI overrides:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Quote the whole key=value pair with single quotes, as in the first two\nexamples above. These quotes are for the benefit of the shell."),(0,r.mdx)("li",{parentName:"ul"},"Do not quote keys."),(0,r.mdx)("li",{parentName:"ul"},"Only quote values if they contain a space. It will work if you always quote\nvalues, but it will turn numbers/dicts/lists into strings (as in the first\nexample above)."),(0,r.mdx)("li",{parentName:"ul"},"When you are quoting values, use double quotes to avoid collision with the\nouter single quoted consumed by the shell.")),(0,r.mdx)("h3",{id:"whitespaces-in-unquoted-values"},"Whitespaces in unquoted values"),(0,r.mdx)("p",null,"Unquoted Override values can contain non leading or trailing whitespaces.\nFor example, ",(0,r.mdx)("inlineCode",{parentName:"p"},"msg=hello world")," is a legal override (key is ",(0,r.mdx)("inlineCode",{parentName:"p"},"msg")," and value is the string ",(0,r.mdx)("inlineCode",{parentName:"p"},"hello world"),").\nNormally, your shell will interpret values with whitespaces as being multiple parameters (",(0,r.mdx)("inlineCode",{parentName:"p"},"key=a b")," would be interpreted as ",(0,r.mdx)("inlineCode",{parentName:"p"},"key=a")," and ",(0,r.mdx)("inlineCode",{parentName:"p"},"b"),").\nTo prevent this you can quote them with a single quote. For example:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-shell"},"$ python my_app.py 'msg=hello world'\n")),(0,r.mdx)("p",null,"Note that trailing and leading whitespace are ignored, the above is equivalent to:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-shell"},"$ python my_app.py 'msg= hello world '\n")),(0,r.mdx)("h3",{id:"escaped-characters-in-unquoted-values"},"Escaped characters in unquoted values"),(0,r.mdx)("p",null,"Hydra's parser considers some characters to be illegal in unquoted strings.\nThese otherwise special characters may be included in unquoted values by escaping them with a ",(0,r.mdx)("inlineCode",{parentName:"p"},"\\"),".\nThese characters are: ",(0,r.mdx)("inlineCode",{parentName:"p"},"\\()[]{}:=, \\t")," (the last two ones being the whitespace and tab characters)."),(0,r.mdx)("p",null,"As an example, in the following ",(0,r.mdx)("inlineCode",{parentName:"p"},"dir")," is set to the string ",(0,r.mdx)("inlineCode",{parentName:"p"},"job{a=1,b=2,c=3}"),":"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-shell"},"$ python my_app.py 'dir=job\\{a\\=1\\,b\\=2\\,c\\=3\\}'\n")),(0,r.mdx)("p",null,"As an alternative to escaping special characters with a backslash, the value containing the special character may be quoted:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-shell"},"$ python my_app.py 'dir=A[B' # parser error\n$ python my_app.py 'dir=\"A[B\"' # ok\n$ python my_app.py 'dir=A\\[B' # ok\n")),(0,r.mdx)("h3",{id:"primitives"},"Primitives"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"id")," : oompa10, loompa_12"),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"null"),": null"),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"int"),": 10, -20, 0, 1_000_000."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"float"),": 3.14, -10e6, inf, -inf, nan."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"bool"),": true, false"),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"dot_path"),": foo.bar"),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"interpolation"),": ${foo.bar}, ${oc.env:USER,me}")),(0,r.mdx)("p",null,"Constants (null, true, false, inf, nan) are case-insensitive."),(0,r.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,r.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,r.mdx)("h5",{parentName:"div"},(0,r.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,r.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,r.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,r.mdx)("div",{parentName:"div",className:"admonition-content"},(0,r.mdx)("p",{parentName:"div"},"Always single-quote interpolations in the shell, to prevent replacement with shell variables:"),(0,r.mdx)("pre",{parentName:"div"},(0,r.mdx)("code",{parentName:"pre",className:"language-shell"},"$ python my_app.py 'dir=/root/${name}'\n")),(0,r.mdx)("p",{parentName:"div"},"In addition, more complex interpolations containing special characters may require being passed within a quoted value\n(note the extra double quotes surrounding the interpolation):"),(0,r.mdx)("pre",{parentName:"div"},(0,r.mdx)("code",{parentName:"pre",className:"language-shell"},"$ python my_app.py 'dir=\"${get_dir: {root: /root, name: ${name}}}\"'\n")))),(0,r.mdx)("h2",{id:"dictionaries-and-lists"},"Dictionaries and Lists"),(0,r.mdx)("h3",{id:"lists"},"Lists"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},"foo=[1,2,3]\nnested=[a,[b,[c]]]\n")),(0,r.mdx)("h3",{id:"dictionaries"},"Dictionaries"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},"foo={a:10,b:20}\nnested={a:10,b:{c:30,d:40}}\n")),(0,r.mdx)("p",null,"Dictionaries are merged, not assigned. The following example illustrates the point:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Input config"',title:'"Input','config"':!0},"db:\n driver: mysql\n user: ???\n pass: ???\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db={user:root,pass:1234}"',title:'"db'},"db:\n driver: mysql\n user: root\n pass: 1234\n")))),(0,r.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,r.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,r.mdx)("h5",{parentName:"div"},(0,r.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,r.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,r.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,r.mdx)("div",{parentName:"div",className:"admonition-content"},(0,r.mdx)("p",{parentName:"div"},"Always single-quote overrides that contains dicts and lists in the shell."))),(0,r.mdx)("h3",{id:"sweeper-syntax"},"Sweeper syntax"),(0,r.mdx)("p",null,"A choice sweep is comma separated list with two or more elements:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-shell",metastring:"script",script:!0},'key=a,b # Simple sweep: ChoiceSweep(a, b)\nkey="a,b","c,d" # Elements can be quoted strings, ChoiceSweep("a,b", "c,d")\nkey=[a,b],[c,d] # Elements can be real lists, ChoiceSweep([a,b], [c,d])\nkey={a:10, b:20},{c:30,d:40} # And dictionaries: ChoiceSweep({a:10, b:20}, {c:30,d:40})\n')),(0,r.mdx)("p",null,"More sweeping options are described in the ",(0,r.mdx)("a",{parentName:"p",href:"/docs/advanced/override_grammar/extended"},"Extended Grammar page"),"."),(0,r.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,r.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,r.mdx)("h5",{parentName:"div"},(0,r.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,r.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,r.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,r.mdx)("div",{parentName:"div",className:"admonition-content"},(0,r.mdx)("p",{parentName:"div"},"You may need to quote your choice sweep in the shell."))),(0,r.mdx)("h3",{id:"functions"},"Functions"),(0,r.mdx)("p",null,"Hydra supports several functions in the command line.\nSee the ",(0,r.mdx)("a",{parentName:"p",href:"/docs/advanced/override_grammar/extended"},"Extended Grammar page")," for more information."),(0,r.mdx)("h2",{id:"working-with-your-shell"},"Working with your shell"),(0,r.mdx)("p",null,"All shells interprets command line inputs and may change what is passed to the process.\nA good way to determine what the shell is doing to your command is to ",(0,r.mdx)("inlineCode",{parentName:"p"},"echo")," it."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-shell",metastring:"script",script:!0},"# bash output\n$ echo foo_{a:10,b:20} ${HOME} [b,c]*\nfoo_a:10 foo_b:20 /home/omry build_helpers\n$ echo 'foo_{a:10,b:20}' '${HOME}' '[b,c]*'\nfoo_{a:10,b:20} ${HOME} [b,c]*\n")),(0,r.mdx)("p",null,"If in doubt, quote a command line element with a ",(0,r.mdx)("strong",{parentName:"p"},"single quote")," (",(0,r.mdx)("inlineCode",{parentName:"p"},"'"),")."),(0,r.mdx)("p",null,"If you want to pass quotes to Hydra in a shell quoted string, it's best to pass double quotes."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-shell",metastring:"script",script:!0},'$ echo \'"hello world"\'\n"hello world"\n')),(0,r.mdx)("p",null,"You can use some shell specific commands to change their behavior, but the cost will be that their behavior will change."),(0,r.mdx)("h3",{id:"bash"},"Bash"),(0,r.mdx)("p",null,"You can disable braces expansion, filename generation (globing) and hist expansion. Please note that this will change\nyour shell behavior for the current session."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-shell",metastring:"script",script:!0},"$ set +o braceexpand -o noglob +o histexpand\n$ echo key1={a:10,b:20} key2=${HOME} key=[b]*\nkey1={a:10,b:20} key2=/home/omry key=[b]*\n# does not help with () though:\n$ echo key=choice(a,b,c)\nbash: syntax error near unexpected token '('\n$ echo 'key=choice(a,b,c)'\nkey=choice(a,b,c)\n")),(0,r.mdx)("h3",{id:"other-shells"},"Other shells"),(0,r.mdx)("p",null,"Send a PR to add information about your favorite shell here."))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/10fbd247.a5c43b43.js b/assets/js/10fbd247.a5c43b43.js new file mode 100644 index 0000000000..bd04b53963 --- /dev/null +++ b/assets/js/10fbd247.a5c43b43.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[9025],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>l,MDXProvider:()=>d,mdx:()=>g,useMDXComponents:()=>u,withMDXComponents:()=>m});var a=n(96540);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(){return i=Object.assign||function(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var l=a.createContext({}),m=function(e){return function(t){var n=u(t.components);return a.createElement(e,i({},t,{components:n}))}},u=function(e){var t=a.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):s(s({},t),e)),n},d=function(e){var t=u(e.components);return a.createElement(l.Provider,{value:t},e.children)},f={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},p=a.forwardRef((function(e,t){var n=e.components,r=e.mdxType,i=e.originalType,o=e.parentName,l=c(e,["components","mdxType","originalType","parentName"]),m=u(n),d=r,p=m["".concat(o,".").concat(d)]||m[d]||f[d]||i;return n?a.createElement(p,s(s({ref:t},l),{},{components:n})):a.createElement(p,s({ref:t},l))}));function g(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var i=n.length,o=new Array(i);o[0]=p;var s={};for(var c in t)hasOwnProperty.call(t,c)&&(s[c]=t[c]);s.originalType=e,s.mdxType="string"==typeof e?e:r,o[1]=s;for(var l=2;l{n.d(t,{A:()=>c,C:()=>l});var a=n(58168),r=n(96540),i=n(75489),o=n(44586),s=n(74098);function c(e){return r.createElement(i.default,(0,a.A)({},e,{to:(t=e.to,c=(0,s.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==c?void 0:c.name)?n:"current"]+t),target:"_blank"}));var t,n,c}function l(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return r.createElement(c,e,r.createElement("span",null,"\xa0"),r.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},72037:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>l,default:()=>f,frontMatter:()=>c,metadata:()=>m,toc:()=>u});var a=n(58168),r=n(98587),i=(n(96540),n(15680)),o=n(49595),s=["components"],c={id:"static_schema",title:"Static schema with many configs"},l=void 0,m={unversionedId:"tutorials/structured_config/static_schema",id:"version-1.0/tutorials/structured_config/static_schema",title:"Static schema with many configs",description:"We have seen that if the name of the config file matches the name of a configs stored in the ConfigStore it will be used to validate the config file automatically.",source:"@site/versioned_docs/version-1.0/tutorials/structured_config/6_static_schema_many_configs.md",sourceDirName:"tutorials/structured_config",slug:"/tutorials/structured_config/static_schema",permalink:"/docs/1.0/tutorials/structured_config/static_schema",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.0/tutorials/structured_config/6_static_schema_many_configs.md",tags:[],version:"1.0",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:6,frontMatter:{id:"static_schema",title:"Static schema with many configs"},sidebar:"version-1.0/docs",previous:{title:"Structured config schema",permalink:"/docs/1.0/tutorials/structured_config/schema"},next:{title:"Dynamic schema with many configs",permalink:"/docs/1.0/tutorials/structured_config/dynamic_schema"}},u=[],d={toc:u};function f(e){var t=e.components,n=(0,r.A)(e,s);return(0,i.mdx)("wrapper",(0,a.A)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,i.mdx)(o.C,{to:"examples/tutorials/structured_configs/6_static_schema_many_configs",mdxType:"ExampleGithubLink"}),(0,i.mdx)("p",null,"We have seen that if the name of the config file matches the name of a configs stored in the ",(0,i.mdx)("inlineCode",{parentName:"p"},"ConfigStore")," it will be used to validate the config file automatically.\nThis is useful if there is a one-to-one mapping between the Structured Configs and the YAML files.\nSuch convenient mapping does not exist when we have many config files and just one schema."),(0,i.mdx)("p",null,"If the config has a static structure, You can define it using Structured Configs.\nAny config merged into this config structure will be validated against the schema you define."),(0,i.mdx)("div",{className:"row"},(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python"},'@dataclass\nclass DBConfig:\n driver: str = MISSING\n host: str = MISSING\n user: str = MISSING\n password: str = MISSING\n\n@dataclass\nclass Config:\n db: DBConfig = MISSING\n\ncs = ConfigStore.instance()\ncs.store(name="config", node=Config)\n\n@hydra.main(config_path="conf", \n config_name="config")\ndef my_app(cfg: Config) -> None:\n print(OmegaConf.to_yaml(cfg))\n\nif __name__ == "__main__":\n my_app()\n\n\n\n'))),(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Config directory"',title:'"Config','directory"':!0},"\u251c\u2500\u2500 config.yaml\n\u2514\u2500\u2500 db\n \u251c\u2500\u2500 prod.yaml\n \u251c\u2500\u2500 qa.yaml\n \u2514\u2500\u2500 staging.yaml\n")),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - db: staging\n")),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/staging.yaml"',title:'"db/staging.yaml"'},"# @package _group_\ndriver: mysql\nhost: mysql001.staging\nuser: root\npassword: root\n")))),(0,i.mdx)("p",null,"In the above example, the 3 yaml files has the structure compatible with the ",(0,i.mdx)("inlineCode",{parentName:"p"},"Config")," dataclass.\nYou can have as many such configs as you want."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Output"',title:'"Output"'},"$ python my_app.py db=prod\ndb:\n driver: mysql\n host: mysql001.prod\n user: root\n password: '1234'\n")))}f.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/10fbd247.c449f108.js b/assets/js/10fbd247.c449f108.js deleted file mode 100644 index 4f18ee2179..0000000000 --- a/assets/js/10fbd247.c449f108.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[9025],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>l,MDXProvider:()=>d,mdx:()=>g,useMDXComponents:()=>u,withMDXComponents:()=>m});var a=n(96540);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(){return i=Object.assign||function(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var l=a.createContext({}),m=function(e){return function(t){var n=u(t.components);return a.createElement(e,i({},t,{components:n}))}},u=function(e){var t=a.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):s(s({},t),e)),n},d=function(e){var t=u(e.components);return a.createElement(l.Provider,{value:t},e.children)},f={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},p=a.forwardRef((function(e,t){var n=e.components,r=e.mdxType,i=e.originalType,o=e.parentName,l=c(e,["components","mdxType","originalType","parentName"]),m=u(n),d=r,p=m["".concat(o,".").concat(d)]||m[d]||f[d]||i;return n?a.createElement(p,s(s({ref:t},l),{},{components:n})):a.createElement(p,s({ref:t},l))}));function g(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var i=n.length,o=new Array(i);o[0]=p;var s={};for(var c in t)hasOwnProperty.call(t,c)&&(s[c]=t[c]);s.originalType=e,s.mdxType="string"==typeof e?e:r,o[1]=s;for(var l=2;l{n.d(t,{A:()=>c,C:()=>l});var a=n(58168),r=n(96540),i=n(75489),o=n(44586),s=n(74098);function c(e){return r.createElement(i.default,(0,a.A)({},e,{to:(t=e.to,c=(0,s.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==c?void 0:c.name)?n:"current"]+t),target:"_blank"}));var t,n,c}function l(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return r.createElement(c,e,r.createElement("span",null,"\xa0"),r.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},72037:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>l,default:()=>f,frontMatter:()=>c,metadata:()=>m,toc:()=>u});var a=n(58168),r=n(98587),i=(n(96540),n(15680)),o=n(49595),s=["components"],c={id:"static_schema",title:"Static schema with many configs"},l=void 0,m={unversionedId:"tutorials/structured_config/static_schema",id:"version-1.0/tutorials/structured_config/static_schema",title:"Static schema with many configs",description:"We have seen that if the name of the config file matches the name of a configs stored in the ConfigStore it will be used to validate the config file automatically.",source:"@site/versioned_docs/version-1.0/tutorials/structured_config/6_static_schema_many_configs.md",sourceDirName:"tutorials/structured_config",slug:"/tutorials/structured_config/static_schema",permalink:"/docs/1.0/tutorials/structured_config/static_schema",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.0/tutorials/structured_config/6_static_schema_many_configs.md",tags:[],version:"1.0",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:6,frontMatter:{id:"static_schema",title:"Static schema with many configs"},sidebar:"version-1.0/docs",previous:{title:"Structured config schema",permalink:"/docs/1.0/tutorials/structured_config/schema"},next:{title:"Dynamic schema with many configs",permalink:"/docs/1.0/tutorials/structured_config/dynamic_schema"}},u=[],d={toc:u};function f(e){var t=e.components,n=(0,r.A)(e,s);return(0,i.mdx)("wrapper",(0,a.A)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,i.mdx)(o.C,{to:"examples/tutorials/structured_configs/6_static_schema_many_configs",mdxType:"ExampleGithubLink"}),(0,i.mdx)("p",null,"We have seen that if the name of the config file matches the name of a configs stored in the ",(0,i.mdx)("inlineCode",{parentName:"p"},"ConfigStore")," it will be used to validate the config file automatically.\nThis is useful if there is a one-to-one mapping between the Structured Configs and the YAML files.\nSuch convenient mapping does not exist when we have many config files and just one schema."),(0,i.mdx)("p",null,"If the config has a static structure, You can define it using Structured Configs.\nAny config merged into this config structure will be validated against the schema you define."),(0,i.mdx)("div",{className:"row"},(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python"},'@dataclass\nclass DBConfig:\n driver: str = MISSING\n host: str = MISSING\n user: str = MISSING\n password: str = MISSING\n\n@dataclass\nclass Config:\n db: DBConfig = MISSING\n\ncs = ConfigStore.instance()\ncs.store(name="config", node=Config)\n\n@hydra.main(config_path="conf", \n config_name="config")\ndef my_app(cfg: Config) -> None:\n print(OmegaConf.to_yaml(cfg))\n\nif __name__ == "__main__":\n my_app()\n\n\n\n'))),(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Config directory"',title:'"Config','directory"':!0},"\u251c\u2500\u2500 config.yaml\n\u2514\u2500\u2500 db\n \u251c\u2500\u2500 prod.yaml\n \u251c\u2500\u2500 qa.yaml\n \u2514\u2500\u2500 staging.yaml\n")),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - db: staging\n")),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/staging.yaml"',title:'"db/staging.yaml"'},"# @package _group_\ndriver: mysql\nhost: mysql001.staging\nuser: root\npassword: root\n")))),(0,i.mdx)("p",null,"In the above example, the 3 yaml files has the structure compatible with the ",(0,i.mdx)("inlineCode",{parentName:"p"},"Config")," dataclass.\nYou can have as many such configs as you want."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Output"',title:'"Output"'},"$ python my_app.py db=prod\ndb:\n driver: mysql\n host: mysql001.prod\n user: root\n password: '1234'\n")))}f.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/120f5b8b.6af4ba12.js b/assets/js/120f5b8b.6af4ba12.js new file mode 100644 index 0000000000..e84d3d3ec0 --- /dev/null +++ b/assets/js/120f5b8b.6af4ba12.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3951],{15680:(e,t,r)=>{r.r(t),r.d(t,{MDXContext:()=>u,MDXProvider:()=>m,mdx:()=>y,useMDXComponents:()=>c,withMDXComponents:()=>p});var n=r(96540);function o(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(o[r]=e[r]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(o[r]=e[r])}return o}var u=n.createContext({}),p=function(e){return function(t){var r=c(t.components);return n.createElement(e,a({},t,{components:r}))}},c=function(e){var t=n.useContext(u),r=t;return e&&(r="function"==typeof e?e(t):l(l({},t),e)),r},m=function(e){var t=c(e.components);return n.createElement(u.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},f=n.forwardRef((function(e,t){var r=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,u=s(e,["components","mdxType","originalType","parentName"]),p=c(r),m=o,f=p["".concat(i,".").concat(m)]||p[m]||d[m]||a;return r?n.createElement(f,l(l({ref:t},u),{},{components:r})):n.createElement(f,l({ref:t},u))}));function y(e,t){var r=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=r.length,i=new Array(a);i[0]=f;var l={};for(var s in t)hasOwnProperty.call(t,s)&&(l[s]=t[s]);l.originalType=e,l.mdxType="string"==typeof e?e:o,i[1]=l;for(var u=2;u{r.r(t),r.d(t,{contentTitle:()=>s,default:()=>m,frontMatter:()=>l,metadata:()=>u,toc:()=>p});var n=r(58168),o=r(98587),a=(r(96540),r(15680)),i=["components"],l={id:"multi-run",title:"Multi-run",sidebar_label:"Multi-run"},s=void 0,u={unversionedId:"tutorial/multi-run",id:"version-0.11/tutorial/multi-run",title:"Multi-run",description:"Sometimes you want to run a parameter sweep.",source:"@site/versioned_docs/version-0.11/tutorial/6_multirun.md",sourceDirName:"tutorial",slug:"/tutorial/multi-run",permalink:"/docs/0.11/tutorial/multi-run",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-0.11/tutorial/6_multirun.md",tags:[],version:"0.11",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:6,frontMatter:{id:"multi-run",title:"Multi-run",sidebar_label:"Multi-run"},sidebar:"version-0.11/docs",previous:{title:"Config composition",permalink:"/docs/0.11/tutorial/composition"},next:{title:"Tab completion",permalink:"/docs/0.11/tutorial/tab_completion"}},p=[],c={toc:p};function m(e){var t=e.components,r=(0,o.A)(e,i);return(0,a.mdx)("wrapper",(0,n.A)({},c,r,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)("p",null,"Sometimes you want to run a parameter sweep.\nTo run a parameter sweep, use the ",(0,a.mdx)("inlineCode",{parentName:"p"},"--multirun")," (",(0,a.mdx)("inlineCode",{parentName:"p"},"-m"),") flag and pass a comma separated list for each\ndimension you want to sweep."),(0,a.mdx)("p",null,"Here is a sweep over the db types (mysql,postgresql) and the schemas (warehouse,support,school).\nOutput does not contain the configuration prints."),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text"}," $ python tutorial/50_composition/my_app.py schema=warehouse,support,school db=mysql,postgresql -m\n[2019-10-01 14:44:16,254] - Launching 6 jobs locally\n[2019-10-01 14:44:16,254] - Sweep output dir : multirun/2019-10-01/14-44-16\n[2019-10-01 14:44:16,254] - #0 : schema=warehouse db=mysql\n[2019-10-01 14:44:16,321] - #1 : schema=warehouse db=postgresql\n[2019-10-01 14:44:16,390] - #2 : schema=support db=mysql\n[2019-10-01 14:44:16,458] - #3 : schema=support db=postgresql\n[2019-10-01 14:44:16,527] - #4 : schema=school db=mysql\n[2019-10-01 14:44:16,602] - #5 : schema=school db=postgresql\n")),(0,a.mdx)("p",null,"The default launcher runs the jobs locally and serially."),(0,a.mdx)("p",null,"There are plans to add additional Launchers, such as a Launcher that launches your application code on AWS."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/120f5b8b.7cef5e5f.js b/assets/js/120f5b8b.7cef5e5f.js deleted file mode 100644 index bad6e80add..0000000000 --- a/assets/js/120f5b8b.7cef5e5f.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3951],{15680:(e,t,r)=>{r.r(t),r.d(t,{MDXContext:()=>u,MDXProvider:()=>m,mdx:()=>y,useMDXComponents:()=>c,withMDXComponents:()=>p});var n=r(96540);function o(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(o[r]=e[r]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(o[r]=e[r])}return o}var u=n.createContext({}),p=function(e){return function(t){var r=c(t.components);return n.createElement(e,a({},t,{components:r}))}},c=function(e){var t=n.useContext(u),r=t;return e&&(r="function"==typeof e?e(t):l(l({},t),e)),r},m=function(e){var t=c(e.components);return n.createElement(u.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},f=n.forwardRef((function(e,t){var r=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,u=s(e,["components","mdxType","originalType","parentName"]),p=c(r),m=o,f=p["".concat(i,".").concat(m)]||p[m]||d[m]||a;return r?n.createElement(f,l(l({ref:t},u),{},{components:r})):n.createElement(f,l({ref:t},u))}));function y(e,t){var r=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=r.length,i=new Array(a);i[0]=f;var l={};for(var s in t)hasOwnProperty.call(t,s)&&(l[s]=t[s]);l.originalType=e,l.mdxType="string"==typeof e?e:o,i[1]=l;for(var u=2;u{r.r(t),r.d(t,{contentTitle:()=>s,default:()=>m,frontMatter:()=>l,metadata:()=>u,toc:()=>p});var n=r(58168),o=r(98587),a=(r(96540),r(15680)),i=["components"],l={id:"multi-run",title:"Multi-run",sidebar_label:"Multi-run"},s=void 0,u={unversionedId:"tutorial/multi-run",id:"version-0.11/tutorial/multi-run",title:"Multi-run",description:"Sometimes you want to run a parameter sweep.",source:"@site/versioned_docs/version-0.11/tutorial/6_multirun.md",sourceDirName:"tutorial",slug:"/tutorial/multi-run",permalink:"/docs/0.11/tutorial/multi-run",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-0.11/tutorial/6_multirun.md",tags:[],version:"0.11",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:6,frontMatter:{id:"multi-run",title:"Multi-run",sidebar_label:"Multi-run"},sidebar:"version-0.11/docs",previous:{title:"Config composition",permalink:"/docs/0.11/tutorial/composition"},next:{title:"Tab completion",permalink:"/docs/0.11/tutorial/tab_completion"}},p=[],c={toc:p};function m(e){var t=e.components,r=(0,o.A)(e,i);return(0,a.mdx)("wrapper",(0,n.A)({},c,r,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)("p",null,"Sometimes you want to run a parameter sweep.\nTo run a parameter sweep, use the ",(0,a.mdx)("inlineCode",{parentName:"p"},"--multirun")," (",(0,a.mdx)("inlineCode",{parentName:"p"},"-m"),") flag and pass a comma separated list for each\ndimension you want to sweep."),(0,a.mdx)("p",null,"Here is a sweep over the db types (mysql,postgresql) and the schemas (warehouse,support,school).\nOutput does not contain the configuration prints."),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text"}," $ python tutorial/50_composition/my_app.py schema=warehouse,support,school db=mysql,postgresql -m\n[2019-10-01 14:44:16,254] - Launching 6 jobs locally\n[2019-10-01 14:44:16,254] - Sweep output dir : multirun/2019-10-01/14-44-16\n[2019-10-01 14:44:16,254] - #0 : schema=warehouse db=mysql\n[2019-10-01 14:44:16,321] - #1 : schema=warehouse db=postgresql\n[2019-10-01 14:44:16,390] - #2 : schema=support db=mysql\n[2019-10-01 14:44:16,458] - #3 : schema=support db=postgresql\n[2019-10-01 14:44:16,527] - #4 : schema=school db=mysql\n[2019-10-01 14:44:16,602] - #5 : schema=school db=postgresql\n")),(0,a.mdx)("p",null,"The default launcher runs the jobs locally and serially."),(0,a.mdx)("p",null,"There are plans to add additional Launchers, such as a Launcher that launches your application code on AWS."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/12111f85.5de1aa5e.js b/assets/js/12111f85.5de1aa5e.js new file mode 100644 index 0000000000..3b7b283c78 --- /dev/null +++ b/assets/js/12111f85.5de1aa5e.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[240],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>o,MDXProvider:()=>c,mdx:()=>g,useMDXComponents:()=>p,withMDXComponents:()=>s});var t=a(96540);function l(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function r(){return r=Object.assign||function(e){for(var n=1;n=0||(l[a]=e[a]);return l}(e,n);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(l[a]=e[a])}return l}var o=t.createContext({}),s=function(e){return function(n){var a=p(n.components);return t.createElement(e,r({},n,{components:a}))}},p=function(e){var n=t.useContext(o),a=n;return e&&(a="function"==typeof e?e(n):d(d({},n),e)),a},c=function(e){var n=p(e.components);return t.createElement(o.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return t.createElement(t.Fragment,{},n)}},f=t.forwardRef((function(e,n){var a=e.components,l=e.mdxType,r=e.originalType,i=e.parentName,o=m(e,["components","mdxType","originalType","parentName"]),s=p(a),c=l,f=s["".concat(i,".").concat(c)]||s[c]||u[c]||r;return a?t.createElement(f,d(d({ref:n},o),{},{components:a})):t.createElement(f,d({ref:n},o))}));function g(e,n){var a=arguments,l=n&&n.mdxType;if("string"==typeof e||l){var r=a.length,i=new Array(r);i[0]=f;var d={};for(var m in n)hasOwnProperty.call(n,m)&&(d[m]=n[m]);d.originalType=e,d.mdxType="string"==typeof e?e:l,i[1]=d;for(var o=2;o{a.r(n),a.d(n,{contentTitle:()=>m,default:()=>c,frontMatter:()=>d,metadata:()=>o,toc:()=>s});var t=a(58168),l=a(98587),r=(a(96540),a(15680)),i=["components"],d={id:"defaults_list",title:"The Defaults List"},m=void 0,o={unversionedId:"advanced/defaults_list",id:"advanced/defaults_list",title:"The Defaults List",description:"Introduction",source:"@site/docs/advanced/defaults_list.md",sourceDirName:"advanced",slug:"/advanced/defaults_list",permalink:"/docs/advanced/defaults_list",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/advanced/defaults_list.md",tags:[],version:"current",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"defaults_list",title:"The Defaults List"},sidebar:"docs",previous:{title:"Extended Override syntax",permalink:"/docs/advanced/override_grammar/extended"},next:{title:"Packages",permalink:"/docs/advanced/overriding_packages"}},s=[{value:"Introduction",id:"introduction",children:[],level:2},{value:"An example",id:"an-example",children:[],level:2},{value:"Overriding Config Group options",id:"overriding-config-group-options",children:[],level:2},{value:"Composition order",id:"composition-order",children:[],level:2},{value:"Interpolation in the Defaults List",id:"interpolation-in-the-defaults-list",children:[{value:"Restrictions:",id:"restrictions",children:[],level:4}],level:2},{value:"Debugging the Defaults List",id:"debugging-the-defaults-list",children:[],level:2},{value:"Related topics",id:"related-topics",children:[],level:2}],p={toc:s};function c(e){var n=e.components,a=(0,l.A)(e,i);return(0,r.mdx)("wrapper",(0,t.A)({},p,a,{components:n,mdxType:"MDXLayout"}),(0,r.mdx)("h2",{id:"introduction"},"Introduction"),(0,r.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,r.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,r.mdx)("h5",{parentName:"div"},(0,r.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,r.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,r.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,r.mdx)("div",{parentName:"div",className:"admonition-content"},(0,r.mdx)("p",{parentName:"div"},"Many of the features described in this page are new. Please report any issues."))),(0,r.mdx)("p",null,"The Defaults List is a list in an input config that instructs Hydra how to build the output config.\nEach input config can have a Defaults List as a top level element. The Defaults List itself\nis not a part of output config."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Defaults List YAML syntax"',title:'"Defaults',List:!0,YAML:!0,'syntax"':!0},"defaults:\n (- CONFIG|GROUP_DEFAULT)*\n\nCONFIG : (CONFIG_GROUP/)?CONFIG_NAME(@PACKAGE)?\nGROUP_DEFAULT : [optional|override]? CONFIG_GROUP(@PACKAGE)?: OPTION\nOPTION : CONFIG_NAME|CONFIG_NAMES|null\n")),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"CONFIG")," : A config to use when creating the output config. e.g. ",(0,r.mdx)("inlineCode",{parentName:"p"},"db/mysql"),", ",(0,r.mdx)("inlineCode",{parentName:"p"},"db/mysql@backup"),"."),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"GROUP_DEFAULT")," : An ",(0,r.mdx)("em",{parentName:"p"},"overridable")," config. e.g. ",(0,r.mdx)("inlineCode",{parentName:"p"},"db: mysql"),", ",(0,r.mdx)("inlineCode",{parentName:"p"},"db@backup: mysql"),"."),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("strong",{parentName:"li"},(0,r.mdx)("em",{parentName:"strong"},"override"))," : Overrides the option of a previously defined GROUP_DEFAULT."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("strong",{parentName:"li"},(0,r.mdx)("em",{parentName:"strong"},"optional"))," : By default, an OPTION that do not exist causes an error; optional suppresses the error. "),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("strong",{parentName:"li"},(0,r.mdx)("em",{parentName:"strong"},"null"))," : A place-holder for a future override. If it is not overridden the entry is ignored.")),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"CONFIG_NAME"),": The name of a config, without the file system extension. e.g. ",(0,r.mdx)("inlineCode",{parentName:"p"},"mysql")," and not ",(0,r.mdx)("inlineCode",{parentName:"p"},"mysql.yaml"),"."),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"CONFIG_NAMES")," : A list of config names. e.g. ",(0,r.mdx)("inlineCode",{parentName:"p"},"[mysql, sqlite]")),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"CONFIG_GROUP")," : A path to a set of configs.",(0,r.mdx)("br",{parentName:"p"}),"\n","The path is relative to the containing config.\nIt can be made absolute by prefixing it with a ",(0,r.mdx)("inlineCode",{parentName:"p"},"/"),".",(0,r.mdx)("br",{parentName:"p"}),"\n","The path separator is ",(0,r.mdx)("inlineCode",{parentName:"p"},"/")," regardless of the operating system."),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"OPTION"),": The currently selected ",(0,r.mdx)("em",{parentName:"p"},"CONFIG_NAME")," or ",(0,r.mdx)("em",{parentName:"p"},"CONFIG_NAMES")," from a ",(0,r.mdx)("em",{parentName:"p"},"CONFIG_GROUP"),". "),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"PACKAGE")," : Where to place the content of the config within the output config.\nIt is relative to the Package of the containing config by default. See ",(0,r.mdx)("a",{parentName:"p",href:"/docs/advanced/overriding_packages"},"Packages"),"."),(0,r.mdx)("h2",{id:"an-example"},"An example"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Config directory structure"',title:'"Config',directory:!0,'structure"':!0},"\u251c\u2500\u2500 server\n\u2502 \u251c\u2500\u2500 db\n\u2502 \u2502 \u251c\u2500\u2500 mysql.yaml\n\u2502 \u2502 \u2514\u2500\u2500 sqlite.yaml\n\u2502 \u2514\u2500\u2500 apache.yaml\n\u2514\u2500\u2500 config.yaml\n")),(0,r.mdx)("p",null,"Input configs:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - server/apache\n\ndebug: false\n\n\n\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/apache.yaml"',title:'"server/apache.yaml"'},"defaults:\n - db: mysql\n\nname: apache\n\n\n\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/db/mysql.yaml"',title:'"server/db/mysql.yaml"'},"name: mysql\n")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/db/sqlite.yaml"',title:'"server/db/sqlite.yaml"'},"name: sqlite\n")))),(0,r.mdx)("p",null,"Output config:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py"',title:'"$',python:!0,'my_app.py"':!0},"server:\n db:\n name: mysql\n name: apache\ndebug: false\n")),(0,r.mdx)("h2",{id:"overriding-config-group-options"},"Overriding Config Group options"),(0,r.mdx)("p",null,"A Config Group's option can be overridden using a new ",(0,r.mdx)("em",{parentName:"p"},"GROUP_DEFAULT")," with the ",(0,r.mdx)("strong",{parentName:"p"},(0,r.mdx)("em",{parentName:"strong"},"override"))," keyword.\nIf a Group Default is overridden more than once, the last one, in depth first order, wins."),(0,r.mdx)("p",null,"Extending the previous example:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {3}',title:'"config.yaml"',"{3}":!0},"defaults:\n - server/apache\n - override server/db: sqlite\n\ndebug: false\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py" {2,3}',title:'"$',python:!0,'my_app.py"':!0,"{2,3}":!0},"server:\n db:\n name: sqlite\n name: apache\ndebug: false\n")))),(0,r.mdx)("p",null,"A Config Group's option can also be overridden via the command line. e.g: "),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre"},"$ python my_app.py server/db=sqlite\n")),(0,r.mdx)("h2",{id:"composition-order"},"Composition order"),(0,r.mdx)("p",null,"The Defaults List is ordered:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"If multiple configs define the same value, the last one wins."),(0,r.mdx)("li",{parentName:"ul"},"If multiple configs contribute to the same dictionary, the result is the combined dictionary.")),(0,r.mdx)("p",null,"By default, the content of a config is overriding the content of configs in the defaults list."),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {5}',title:'"config.yaml"',"{5}":!0},"defaults:\n - db: mysql \n\ndb:\n host: backup\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Result: db.host from config" {3}',title:'"Result:',"db.host":!0,from:!0,'config"':!0,"{3}":!0},"db:\n driver: mysql # db/mysql.yaml\n host: backup # config.yaml\n port: 3306 # db/mysql.yaml\n\n")))),(0,r.mdx)("p",null,"The ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," entry determines the relative position of ",(0,r.mdx)("strong",{parentName:"p"},"this")," config in the Defaults List.\nIf it is not specified, it is added automatically as the last item."),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {2,6}',title:'"config.yaml"',"{2,6}":!0},"defaults:\n - _self_\n - db: mysql # Overrides this config \n\ndb:\n host: backup\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Result: All values from db/mysql" {3}',title:'"Result:',All:!0,values:!0,from:!0,'db/mysql"':!0,"{3}":!0},"db:\n driver: mysql # db/mysql.yaml\n host: localhost # db/mysql.yaml\n port: 3306 # db/mysql.yaml\n\n\n")))),(0,r.mdx)("p",null,"With ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," at the top of the Defaults List, the host field defined in ",(0,r.mdx)("em",{parentName:"p"},"config.yaml")," now precedes the host field defined\nin ",(0,r.mdx)("em",{parentName:"p"},"db/mysql.yaml"),", and as a result is overridden."),(0,r.mdx)("h2",{id:"interpolation-in-the-defaults-list"},"Interpolation in the Defaults List"),(0,r.mdx)("p",null,"Config Group Options can be selected using interpolation."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - server: apache\n - db: mysql\n - combination_specific_config: ${server}_${db} # apache_mysql\n")),(0,r.mdx)("p",null,"Interpolation keys can be config groups with any @package overrides.",(0,r.mdx)("br",{parentName:"p"}),"\n","For example: ",(0,r.mdx)("inlineCode",{parentName:"p"},"${db/engine}"),", ",(0,r.mdx)("inlineCode",{parentName:"p"},"${db@backup}")),(0,r.mdx)("p",null,"The selected option for ",(0,r.mdx)("em",{parentName:"p"},"combination_specific_config")," depends on the final selected options for ",(0,r.mdx)("em",{parentName:"p"},"db")," and ",(0,r.mdx)("em",{parentName:"p"},"server"),".",(0,r.mdx)("br",{parentName:"p"}),"\n","e.g., If ",(0,r.mdx)("em",{parentName:"p"},"db")," is overridden to ",(0,r.mdx)("em",{parentName:"p"},"sqlite"),", ",(0,r.mdx)("em",{parentName:"p"},"combination_specific_config")," will become ",(0,r.mdx)("em",{parentName:"p"},"apache_sqlite"),"."),(0,r.mdx)("h4",{id:"restrictions"},"Restrictions:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Interpolation keys in the Defaults List cannot reference values in the Final Config Object (it does not yet exist)."),(0,r.mdx)("li",{parentName:"ul"},"Defaults List interpolation keys are absolute (even in nested configs)."),(0,r.mdx)("li",{parentName:"ul"},"The subtree expanded by an Interpolated Config may not contain Default List overrides.")),(0,r.mdx)("p",null,"See ",(0,r.mdx)("a",{parentName:"p",href:"/docs/patterns/specializing_config"},"Patterns/Specializing Configs")," for more information."),(0,r.mdx)("h2",{id:"debugging-the-defaults-list"},"Debugging the Defaults List"),(0,r.mdx)("p",null,"Hydra's config composition process is as follows:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"The Defaults Tree is created."),(0,r.mdx)("li",{parentName:"ul"},"The Final Defaults List is created via a DFS walk of the Defaults Tree."),(0,r.mdx)("li",{parentName:"ul"},"The Output Config is composed from the entries in the Final Defaults List.")),(0,r.mdx)("p",null,"You can inspect these artifacts via command line flags:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"--info defaults-tree")," shows the Defaults Tree."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"--info defaults")," Shows the Final Defaults List."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"--cfg job|hydra|all")," Shows the Output Config.")),(0,r.mdx)("p",null,"Example outputs:"),(0,r.mdx)("details",null,(0,r.mdx)("summary",null,"python my_app.py ",(0,r.mdx)("b",null,"--info defaults-tree")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title=""',title:'""'},":\n hydra/config:\n hydra/hydra_logging: default\n hydra/job_logging: default\n hydra/launcher: basic\n hydra/sweeper: basic\n hydra/output: default\n hydra/help: default\n hydra/hydra_help: default\n _self_\n config:\n server/apache:\n server/db: mysql\n _self_\n _self_\n"))),(0,r.mdx)("details",null,(0,r.mdx)("summary",null,"python my_app.py ",(0,r.mdx)("b",null,"--info defaults")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-text"},"Defaults List\n*************\n| Config path | Package | _self_ | Parent | \n-------------------------------------------------------------------------------\n| hydra/hydra_logging/default | hydra.hydra_logging | False | hydra/config |\n| hydra/job_logging/default | hydra.job_logging | False | hydra/config |\n| hydra/launcher/basic | hydra.launcher | False | hydra/config |\n| hydra/sweeper/basic | hydra.sweeper | False | hydra/config |\n| hydra/output/default | hydra | False | hydra/config |\n| hydra/help/default | hydra.help | False | hydra/config |\n| hydra/hydra_help/default | hydra.hydra_help | False | hydra/config |\n| hydra/config | hydra | True | |\n| server/db/mysql | server.db | False | server/apache |\n| server/apache | server | True | config |\n| config | | True | |\n-------------------------------------------------------------------------------\n"))),(0,r.mdx)("details",null,(0,r.mdx)("summary",null,"python my_app.py ",(0,r.mdx)("b",null,"--cfg job")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml"},"server:\n db:\n name: mysql\n name: apache\ndebug: false\n"))),(0,r.mdx)("h2",{id:"related-topics"},"Related topics"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("a",{parentName:"li",href:"/docs/advanced/overriding_packages"},"Packages")),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("a",{parentName:"li",href:"/docs/patterns/extending_configs"},"Common Patterns/Extending Configs")),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("a",{parentName:"li",href:"/docs/patterns/configuring_experiments"},"Common Patterns/Configuring Experiments")),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("a",{parentName:"li",href:"/docs/patterns/select_multiple_configs_from_config_group"},"Selecting multiple configs from a Config Group"))))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/12111f85.9137afcd.js b/assets/js/12111f85.9137afcd.js deleted file mode 100644 index 39890ec8a8..0000000000 --- a/assets/js/12111f85.9137afcd.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[240],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>o,MDXProvider:()=>c,mdx:()=>g,useMDXComponents:()=>p,withMDXComponents:()=>s});var t=a(96540);function l(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function r(){return r=Object.assign||function(e){for(var n=1;n=0||(l[a]=e[a]);return l}(e,n);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(l[a]=e[a])}return l}var o=t.createContext({}),s=function(e){return function(n){var a=p(n.components);return t.createElement(e,r({},n,{components:a}))}},p=function(e){var n=t.useContext(o),a=n;return e&&(a="function"==typeof e?e(n):d(d({},n),e)),a},c=function(e){var n=p(e.components);return t.createElement(o.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return t.createElement(t.Fragment,{},n)}},f=t.forwardRef((function(e,n){var a=e.components,l=e.mdxType,r=e.originalType,i=e.parentName,o=m(e,["components","mdxType","originalType","parentName"]),s=p(a),c=l,f=s["".concat(i,".").concat(c)]||s[c]||u[c]||r;return a?t.createElement(f,d(d({ref:n},o),{},{components:a})):t.createElement(f,d({ref:n},o))}));function g(e,n){var a=arguments,l=n&&n.mdxType;if("string"==typeof e||l){var r=a.length,i=new Array(r);i[0]=f;var d={};for(var m in n)hasOwnProperty.call(n,m)&&(d[m]=n[m]);d.originalType=e,d.mdxType="string"==typeof e?e:l,i[1]=d;for(var o=2;o{a.r(n),a.d(n,{contentTitle:()=>m,default:()=>c,frontMatter:()=>d,metadata:()=>o,toc:()=>s});var t=a(58168),l=a(98587),r=(a(96540),a(15680)),i=["components"],d={id:"defaults_list",title:"The Defaults List"},m=void 0,o={unversionedId:"advanced/defaults_list",id:"advanced/defaults_list",title:"The Defaults List",description:"Introduction",source:"@site/docs/advanced/defaults_list.md",sourceDirName:"advanced",slug:"/advanced/defaults_list",permalink:"/docs/advanced/defaults_list",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/advanced/defaults_list.md",tags:[],version:"current",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"defaults_list",title:"The Defaults List"},sidebar:"docs",previous:{title:"Extended Override syntax",permalink:"/docs/advanced/override_grammar/extended"},next:{title:"Packages",permalink:"/docs/advanced/overriding_packages"}},s=[{value:"Introduction",id:"introduction",children:[],level:2},{value:"An example",id:"an-example",children:[],level:2},{value:"Overriding Config Group options",id:"overriding-config-group-options",children:[],level:2},{value:"Composition order",id:"composition-order",children:[],level:2},{value:"Interpolation in the Defaults List",id:"interpolation-in-the-defaults-list",children:[{value:"Restrictions:",id:"restrictions",children:[],level:4}],level:2},{value:"Debugging the Defaults List",id:"debugging-the-defaults-list",children:[],level:2},{value:"Related topics",id:"related-topics",children:[],level:2}],p={toc:s};function c(e){var n=e.components,a=(0,l.A)(e,i);return(0,r.mdx)("wrapper",(0,t.A)({},p,a,{components:n,mdxType:"MDXLayout"}),(0,r.mdx)("h2",{id:"introduction"},"Introduction"),(0,r.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,r.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,r.mdx)("h5",{parentName:"div"},(0,r.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,r.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,r.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,r.mdx)("div",{parentName:"div",className:"admonition-content"},(0,r.mdx)("p",{parentName:"div"},"Many of the features described in this page are new. Please report any issues."))),(0,r.mdx)("p",null,"The Defaults List is a list in an input config that instructs Hydra how to build the output config.\nEach input config can have a Defaults List as a top level element. The Defaults List itself\nis not a part of output config."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Defaults List YAML syntax"',title:'"Defaults',List:!0,YAML:!0,'syntax"':!0},"defaults:\n (- CONFIG|GROUP_DEFAULT)*\n\nCONFIG : (CONFIG_GROUP/)?CONFIG_NAME(@PACKAGE)?\nGROUP_DEFAULT : [optional|override]? CONFIG_GROUP(@PACKAGE)?: OPTION\nOPTION : CONFIG_NAME|CONFIG_NAMES|null\n")),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"CONFIG")," : A config to use when creating the output config. e.g. ",(0,r.mdx)("inlineCode",{parentName:"p"},"db/mysql"),", ",(0,r.mdx)("inlineCode",{parentName:"p"},"db/mysql@backup"),"."),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"GROUP_DEFAULT")," : An ",(0,r.mdx)("em",{parentName:"p"},"overridable")," config. e.g. ",(0,r.mdx)("inlineCode",{parentName:"p"},"db: mysql"),", ",(0,r.mdx)("inlineCode",{parentName:"p"},"db@backup: mysql"),"."),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("strong",{parentName:"li"},(0,r.mdx)("em",{parentName:"strong"},"override"))," : Overrides the option of a previously defined GROUP_DEFAULT."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("strong",{parentName:"li"},(0,r.mdx)("em",{parentName:"strong"},"optional"))," : By default, an OPTION that do not exist causes an error; optional suppresses the error. "),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("strong",{parentName:"li"},(0,r.mdx)("em",{parentName:"strong"},"null"))," : A place-holder for a future override. If it is not overridden the entry is ignored.")),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"CONFIG_NAME"),": The name of a config, without the file system extension. e.g. ",(0,r.mdx)("inlineCode",{parentName:"p"},"mysql")," and not ",(0,r.mdx)("inlineCode",{parentName:"p"},"mysql.yaml"),"."),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"CONFIG_NAMES")," : A list of config names. e.g. ",(0,r.mdx)("inlineCode",{parentName:"p"},"[mysql, sqlite]")),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"CONFIG_GROUP")," : A path to a set of configs.",(0,r.mdx)("br",{parentName:"p"}),"\n","The path is relative to the containing config.\nIt can be made absolute by prefixing it with a ",(0,r.mdx)("inlineCode",{parentName:"p"},"/"),".",(0,r.mdx)("br",{parentName:"p"}),"\n","The path separator is ",(0,r.mdx)("inlineCode",{parentName:"p"},"/")," regardless of the operating system."),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"OPTION"),": The currently selected ",(0,r.mdx)("em",{parentName:"p"},"CONFIG_NAME")," or ",(0,r.mdx)("em",{parentName:"p"},"CONFIG_NAMES")," from a ",(0,r.mdx)("em",{parentName:"p"},"CONFIG_GROUP"),". "),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"PACKAGE")," : Where to place the content of the config within the output config.\nIt is relative to the Package of the containing config by default. See ",(0,r.mdx)("a",{parentName:"p",href:"/docs/advanced/overriding_packages"},"Packages"),"."),(0,r.mdx)("h2",{id:"an-example"},"An example"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Config directory structure"',title:'"Config',directory:!0,'structure"':!0},"\u251c\u2500\u2500 server\n\u2502 \u251c\u2500\u2500 db\n\u2502 \u2502 \u251c\u2500\u2500 mysql.yaml\n\u2502 \u2502 \u2514\u2500\u2500 sqlite.yaml\n\u2502 \u2514\u2500\u2500 apache.yaml\n\u2514\u2500\u2500 config.yaml\n")),(0,r.mdx)("p",null,"Input configs:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - server/apache\n\ndebug: false\n\n\n\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/apache.yaml"',title:'"server/apache.yaml"'},"defaults:\n - db: mysql\n\nname: apache\n\n\n\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/db/mysql.yaml"',title:'"server/db/mysql.yaml"'},"name: mysql\n")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/db/sqlite.yaml"',title:'"server/db/sqlite.yaml"'},"name: sqlite\n")))),(0,r.mdx)("p",null,"Output config:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py"',title:'"$',python:!0,'my_app.py"':!0},"server:\n db:\n name: mysql\n name: apache\ndebug: false\n")),(0,r.mdx)("h2",{id:"overriding-config-group-options"},"Overriding Config Group options"),(0,r.mdx)("p",null,"A Config Group's option can be overridden using a new ",(0,r.mdx)("em",{parentName:"p"},"GROUP_DEFAULT")," with the ",(0,r.mdx)("strong",{parentName:"p"},(0,r.mdx)("em",{parentName:"strong"},"override"))," keyword.\nIf a Group Default is overridden more than once, the last one, in depth first order, wins."),(0,r.mdx)("p",null,"Extending the previous example:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {3}',title:'"config.yaml"',"{3}":!0},"defaults:\n - server/apache\n - override server/db: sqlite\n\ndebug: false\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py" {2,3}',title:'"$',python:!0,'my_app.py"':!0,"{2,3}":!0},"server:\n db:\n name: sqlite\n name: apache\ndebug: false\n")))),(0,r.mdx)("p",null,"A Config Group's option can also be overridden via the command line. e.g: "),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre"},"$ python my_app.py server/db=sqlite\n")),(0,r.mdx)("h2",{id:"composition-order"},"Composition order"),(0,r.mdx)("p",null,"The Defaults List is ordered:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"If multiple configs define the same value, the last one wins."),(0,r.mdx)("li",{parentName:"ul"},"If multiple configs contribute to the same dictionary, the result is the combined dictionary.")),(0,r.mdx)("p",null,"By default, the content of a config is overriding the content of configs in the defaults list."),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {5}',title:'"config.yaml"',"{5}":!0},"defaults:\n - db: mysql \n\ndb:\n host: backup\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Result: db.host from config" {3}',title:'"Result:',"db.host":!0,from:!0,'config"':!0,"{3}":!0},"db:\n driver: mysql # db/mysql.yaml\n host: backup # config.yaml\n port: 3306 # db/mysql.yaml\n\n")))),(0,r.mdx)("p",null,"The ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," entry determines the relative position of ",(0,r.mdx)("strong",{parentName:"p"},"this")," config in the Defaults List.\nIf it is not specified, it is added automatically as the last item."),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {2,6}',title:'"config.yaml"',"{2,6}":!0},"defaults:\n - _self_\n - db: mysql # Overrides this config \n\ndb:\n host: backup\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Result: All values from db/mysql" {3}',title:'"Result:',All:!0,values:!0,from:!0,'db/mysql"':!0,"{3}":!0},"db:\n driver: mysql # db/mysql.yaml\n host: localhost # db/mysql.yaml\n port: 3306 # db/mysql.yaml\n\n\n")))),(0,r.mdx)("p",null,"With ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," at the top of the Defaults List, the host field defined in ",(0,r.mdx)("em",{parentName:"p"},"config.yaml")," now precedes the host field defined\nin ",(0,r.mdx)("em",{parentName:"p"},"db/mysql.yaml"),", and as a result is overridden."),(0,r.mdx)("h2",{id:"interpolation-in-the-defaults-list"},"Interpolation in the Defaults List"),(0,r.mdx)("p",null,"Config Group Options can be selected using interpolation."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - server: apache\n - db: mysql\n - combination_specific_config: ${server}_${db} # apache_mysql\n")),(0,r.mdx)("p",null,"Interpolation keys can be config groups with any @package overrides.",(0,r.mdx)("br",{parentName:"p"}),"\n","For example: ",(0,r.mdx)("inlineCode",{parentName:"p"},"${db/engine}"),", ",(0,r.mdx)("inlineCode",{parentName:"p"},"${db@backup}")),(0,r.mdx)("p",null,"The selected option for ",(0,r.mdx)("em",{parentName:"p"},"combination_specific_config")," depends on the final selected options for ",(0,r.mdx)("em",{parentName:"p"},"db")," and ",(0,r.mdx)("em",{parentName:"p"},"server"),".",(0,r.mdx)("br",{parentName:"p"}),"\n","e.g., If ",(0,r.mdx)("em",{parentName:"p"},"db")," is overridden to ",(0,r.mdx)("em",{parentName:"p"},"sqlite"),", ",(0,r.mdx)("em",{parentName:"p"},"combination_specific_config")," will become ",(0,r.mdx)("em",{parentName:"p"},"apache_sqlite"),"."),(0,r.mdx)("h4",{id:"restrictions"},"Restrictions:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Interpolation keys in the Defaults List cannot reference values in the Final Config Object (it does not yet exist)."),(0,r.mdx)("li",{parentName:"ul"},"Defaults List interpolation keys are absolute (even in nested configs)."),(0,r.mdx)("li",{parentName:"ul"},"The subtree expanded by an Interpolated Config may not contain Default List overrides.")),(0,r.mdx)("p",null,"See ",(0,r.mdx)("a",{parentName:"p",href:"/docs/patterns/specializing_config"},"Patterns/Specializing Configs")," for more information."),(0,r.mdx)("h2",{id:"debugging-the-defaults-list"},"Debugging the Defaults List"),(0,r.mdx)("p",null,"Hydra's config composition process is as follows:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"The Defaults Tree is created."),(0,r.mdx)("li",{parentName:"ul"},"The Final Defaults List is created via a DFS walk of the Defaults Tree."),(0,r.mdx)("li",{parentName:"ul"},"The Output Config is composed from the entries in the Final Defaults List.")),(0,r.mdx)("p",null,"You can inspect these artifacts via command line flags:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"--info defaults-tree")," shows the Defaults Tree."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"--info defaults")," Shows the Final Defaults List."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"--cfg job|hydra|all")," Shows the Output Config.")),(0,r.mdx)("p",null,"Example outputs:"),(0,r.mdx)("details",null,(0,r.mdx)("summary",null,"python my_app.py ",(0,r.mdx)("b",null,"--info defaults-tree")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title=""',title:'""'},":\n hydra/config:\n hydra/hydra_logging: default\n hydra/job_logging: default\n hydra/launcher: basic\n hydra/sweeper: basic\n hydra/output: default\n hydra/help: default\n hydra/hydra_help: default\n _self_\n config:\n server/apache:\n server/db: mysql\n _self_\n _self_\n"))),(0,r.mdx)("details",null,(0,r.mdx)("summary",null,"python my_app.py ",(0,r.mdx)("b",null,"--info defaults")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-text"},"Defaults List\n*************\n| Config path | Package | _self_ | Parent | \n-------------------------------------------------------------------------------\n| hydra/hydra_logging/default | hydra.hydra_logging | False | hydra/config |\n| hydra/job_logging/default | hydra.job_logging | False | hydra/config |\n| hydra/launcher/basic | hydra.launcher | False | hydra/config |\n| hydra/sweeper/basic | hydra.sweeper | False | hydra/config |\n| hydra/output/default | hydra | False | hydra/config |\n| hydra/help/default | hydra.help | False | hydra/config |\n| hydra/hydra_help/default | hydra.hydra_help | False | hydra/config |\n| hydra/config | hydra | True | |\n| server/db/mysql | server.db | False | server/apache |\n| server/apache | server | True | config |\n| config | | True | |\n-------------------------------------------------------------------------------\n"))),(0,r.mdx)("details",null,(0,r.mdx)("summary",null,"python my_app.py ",(0,r.mdx)("b",null,"--cfg job")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml"},"server:\n db:\n name: mysql\n name: apache\ndebug: false\n"))),(0,r.mdx)("h2",{id:"related-topics"},"Related topics"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("a",{parentName:"li",href:"/docs/advanced/overriding_packages"},"Packages")),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("a",{parentName:"li",href:"/docs/patterns/extending_configs"},"Common Patterns/Extending Configs")),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("a",{parentName:"li",href:"/docs/patterns/configuring_experiments"},"Common Patterns/Configuring Experiments")),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("a",{parentName:"li",href:"/docs/patterns/select_multiple_configs_from_config_group"},"Selecting multiple configs from a Config Group"))))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/13a26e00.04cacd2f.js b/assets/js/13a26e00.04cacd2f.js deleted file mode 100644 index eb5e7b3b2c..0000000000 --- a/assets/js/13a26e00.04cacd2f.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[6297],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>m,MDXProvider:()=>c,mdx:()=>y,useMDXComponents:()=>s,withMDXComponents:()=>p});var r=a(96540);function t(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function l(){return l=Object.assign||function(e){for(var n=1;n=0||(t[a]=e[a]);return t}(e,n);if(Object.getOwnPropertySymbols){var l=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(t[a]=e[a])}return t}var m=r.createContext({}),p=function(e){return function(n){var a=s(n.components);return r.createElement(e,l({},n,{components:a}))}},s=function(e){var n=r.useContext(m),a=n;return e&&(a="function"==typeof e?e(n):o(o({},n),e)),a},c=function(e){var n=s(e.components);return r.createElement(m.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},h=r.forwardRef((function(e,n){var a=e.components,t=e.mdxType,l=e.originalType,i=e.parentName,m=d(e,["components","mdxType","originalType","parentName"]),p=s(a),c=t,h=p["".concat(i,".").concat(c)]||p[c]||u[c]||l;return a?r.createElement(h,o(o({ref:n},m),{},{components:a})):r.createElement(h,o({ref:n},m))}));function y(e,n){var a=arguments,t=n&&n.mdxType;if("string"==typeof e||t){var l=a.length,i=new Array(l);i[0]=h;var o={};for(var d in n)hasOwnProperty.call(n,d)&&(o[d]=n[d]);o.originalType=e,o.mdxType="string"==typeof e?e:t,i[1]=o;for(var m=2;m{a.d(n,{A:()=>d,C:()=>m});var r=a(58168),t=a(96540),l=a(75489),i=a(44586),o=a(74098);function d(e){return t.createElement(l.default,(0,r.A)({},e,{to:(n=e.to,d=(0,o.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(a=null==d?void 0:d.name)?a:"current"]+n),target:"_blank"}));var n,a,d}function m(e){var n,a=null!=(n=e.text)?n:"Example (Click Here)";return t.createElement(d,e,t.createElement("span",null,"\xa0"),t.createElement("img",{src:"https://img.shields.io/badge/-"+a+"-informational",alt:"Example (Click Here)"}))}},84850:(e,n,a)=>{a.r(n),a.d(n,{contentTitle:()=>m,default:()=>u,frontMatter:()=>d,metadata:()=>p,toc:()=>s});var r=a(58168),t=a(98587),l=(a(96540),a(15680)),i=a(49595),o=["components"],d={id:"ray_launcher",title:"Ray Launcher plugin",sidebar_label:"Ray Launcher plugin"},m=void 0,p={unversionedId:"plugins/ray_launcher",id:"version-1.1/plugins/ray_launcher",title:"Ray Launcher plugin",description:"PyPI",source:"@site/versioned_docs/version-1.1/plugins/ray_launcher.md",sourceDirName:"plugins",slug:"/plugins/ray_launcher",permalink:"/docs/1.1/plugins/ray_launcher",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/plugins/ray_launcher.md",tags:[],version:"1.1",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"ray_launcher",title:"Ray Launcher plugin",sidebar_label:"Ray Launcher plugin"},sidebar:"version-1.1/docs",previous:{title:"Joblib Launcher plugin",permalink:"/docs/1.1/plugins/joblib_launcher"},next:{title:"RQ Launcher plugin",permalink:"/docs/1.1/plugins/rq_launcher"}},s=[{value:"Installation",id:"installation",children:[],level:3},{value:"Usage",id:"usage",children:[],level:3},{value:"ray_aws launcher",id:"ray_aws-launcher",children:[{value:"Examples",id:"examples",children:[{value:"Manage Cluster LifeCycle",id:"manage-cluster-lifecycle",children:[],level:5},{value:"Configure Ray Logging",id:"configure-ray-logging",children:[],level:5}],level:4}],level:3},{value:"ray launcher",id:"ray-launcher",children:[],level:3},{value:"Configure ray.init() and ray.remote()",id:"configure-rayinit-and-rayremote",children:[],level:3}],c={toc:s};function u(e){var n=e.components,a=(0,t.A)(e,o);return(0,l.mdx)("wrapper",(0,r.A)({},c,a,{components:n,mdxType:"MDXLayout"}),(0,l.mdx)("p",null,(0,l.mdx)("a",{parentName:"p",href:"https://pypi.org/project/hydra-ray-launcher/"},(0,l.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/v/hydra-ray-launcher",alt:"PyPI"})),"\n",(0,l.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/l/hydra-ray-launcher",alt:"PyPI - License"}),"\n",(0,l.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/pyversions/hydra-ray-launcher",alt:"PyPI - Python Version"}),"\n",(0,l.mdx)("a",{parentName:"p",href:"https://pypistats.org/packages/hydra-ray-launcher"},(0,l.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/dm/hydra-ray-launcher.svg",alt:"PyPI - Downloads"})),(0,l.mdx)(i.C,{text:"Example application",to:"plugins/hydra_ray_launcher/examples",mdxType:"ExampleGithubLink"}),(0,l.mdx)(i.C,{text:"Plugin source",to:"plugins/hydra_ray_launcher",mdxType:"ExampleGithubLink"})),(0,l.mdx)("p",null,"The Ray Launcher plugin provides 2 launchers: ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray_aws")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray"),".\n",(0,l.mdx)("inlineCode",{parentName:"p"},"ray_aws")," launches jobs remotely on AWS and is built on top of ",(0,l.mdx)("a",{parentName:"p",href:"https://docs.ray.io/en/releases-1.3.0/cluster/sdk.html"},"ray autoscaler sdk"),". ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray")," launches jobs on your local machine or existing ray cluster. "),(0,l.mdx)("h3",{id:"installation"},"Installation"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ pip install hydra-ray-launcher --upgrade\n")),(0,l.mdx)("h3",{id:"usage"},"Usage"),(0,l.mdx)("p",null,"Once installed, add ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra/launcher=ray_aws")," or ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra/launcher=ray")," to your command line. Alternatively, override ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra/launcher")," in your config:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - override hydra/launcher: ray_aws\n")),(0,l.mdx)("p",null,"There are several standard approaches for configuring plugins. Check ",(0,l.mdx)("a",{parentName:"p",href:"/docs/1.1/patterns/configuring_plugins"},"this page")," for more information."),(0,l.mdx)("h3",{id:"ray_aws-launcher"},(0,l.mdx)("inlineCode",{parentName:"h3"},"ray_aws")," launcher"),(0,l.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,l.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,l.mdx)("h5",{parentName:"div"},(0,l.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,l.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,l.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,l.mdx)("div",{parentName:"div",className:"admonition-content"},(0,l.mdx)("p",{parentName:"div"},(0,l.mdx)("inlineCode",{parentName:"p"},"ray_aws")," launcher is built on top of ray's ",(0,l.mdx)("a",{parentName:"p",href:"https://docs.ray.io/en/releases-1.3.0/cluster/sdk.html"},"autoscaler sdk"),". To get started, you need to\n",(0,l.mdx)("a",{parentName:"p",href:"https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html"},"config your AWS credentials"),".\n",(0,l.mdx)("inlineCode",{parentName:"p"},"ray autoscaler sdk")," expects your AWS credentials have certain permissions for ",(0,l.mdx)("a",{parentName:"p",href:"https://aws.amazon.com/ec2"},(0,l.mdx)("inlineCode",{parentName:"a"},"EC2"))," and ",(0,l.mdx)("a",{parentName:"p",href:"https://aws.amazon.com/iam"},(0,l.mdx)("inlineCode",{parentName:"a"},"IAM")),". Read ",(0,l.mdx)("a",{parentName:"p",href:"https://github.com/ray-project/ray/issues/9327"},"this")," for more information."))),(0,l.mdx)("p",null,(0,l.mdx)("inlineCode",{parentName:"p"},"ray autoscaler sdk")," expects a configuration for the EC2 cluster; we've schematized the configs in ",(0,l.mdx)(i.A,{to:"plugins/hydra_ray_launcher/hydra_plugins/hydra_ray_launcher/_config.py",mdxType:"GithubLink"},"here")),(0,l.mdx)("details",null,(0,l.mdx)("summary",null,"Discover ray_aws launcher's config"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ python my_app.py hydra/launcher=ray_aws --cfg hydra -p hydra.launcher\n# @package hydra.launcher\n_target_: hydra_plugins.hydra_ray_launcher.ray_aws_launcher.RayAWSLauncher\nenv_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.1.0.dev3\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\nray:\n init:\n address: null\n remote: {}\n cluster:\n cluster_name: default\n min_workers: 0\n max_workers: 1\n initial_workers: 0\n autoscaling_mode: default\n target_utilization_fraction: 0.8\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 head_node:\n InstanceType: m5.large\n ImageId: ami-008d8ed4bd7dc2485\n worker_nodes:\n InstanceType: m5.large\n ImageId: ami-008d8ed4bd7dc2485\n file_mounts: {}\n initialization_commands: []\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\n --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\nstop_cluster: true\nsync_up:\n source_dir: null\n target_dir: null\n include: []\n exclude: []\nsync_down:\n source_dir: null\n target_dir: null\n include: []\n exclude: []\nlogging:\n log_style: auto\n color_mode: auto\n verbosity: 0\ncreate_update_cluster:\n no_restart: false\n restart_only: false\n no_config_cache: false\nteardown_cluster:\n workers_only: false\n keep_min_workers: false\n"))),(0,l.mdx)("h4",{id:"examples"},"Examples"),(0,l.mdx)("p",null,"The following examples can be found ",(0,l.mdx)(i.A,{to:"plugins/hydra_ray_launcher/examples",mdxType:"GithubLink"},"here"),"."),(0,l.mdx)("details",null,(0,l.mdx)("summary",null,"Simple app"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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\nCluster: default\n...\nINFO 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)\nDestroying cluster. Confirm [y/N]: y [automatic, due to --yes]\n...\nNo nodes remaining.\n\n"))),(0,l.mdx)("details",null,(0,l.mdx)("summary",null,"Upload & Download from remote cluster"),(0,l.mdx)("p",null,"If your application is dependent on multiple modules, you can configure ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.sync_up")," to upload dependency modules to the remote cluster.\nYou can also configure ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.sync_down")," to download output from remote cluster if needed. This functionality is built on top of ",(0,l.mdx)("inlineCode",{parentName:"p"},"rsync"),", ",(0,l.mdx)("inlineCode",{parentName:"p"},"include")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"exclude")," is consistent with how it works in ",(0,l.mdx)("inlineCode",{parentName:"p"},"rsync"),"."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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\nCluster: default\n...\nINFO 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\nLoaded cached provider configuration\n...\n[HYDRA] Output: receiving file list ... done\n16-32-25/\n16-32-25/0/\n16-32-25/0/checkpoint/\n16-32-25/0/checkpoint/checkpoint_1.pt\n16-32-25/1/\n16-32-25/1/checkpoint/\n16-32-25/1/checkpoint/checkpoint_2.pt\n16-32-25/2/\n16-32-25/2/checkpoint/\n16-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)\nDestroying cluster. Confirm [y/N]: y [automatic, due to --yes]\n...\nNo nodes remaining.\n\n"))),(0,l.mdx)("h5",{id:"manage-cluster-lifecycle"},"Manage Cluster LifeCycle"),(0,l.mdx)("p",null,"You can manage the Ray EC2 cluster lifecycle by configuring the flags provided by the plugin:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Default setting (no need to specify on commandline): delete cluster after job finishes remotely:"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.stop_cluster=true\nhydra.launcher.ray.cluster.provider.cache_stopped_nodes=false\nhydra.launcher.teardown_cluster.workers_only=false\nhydra.launcher.teardown_cluster.keep_min_workers=false\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Keep cluster running after jobs finishes remotely"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.stop_cluster=false\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Power off EC2 instances and control node termination using ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.cluster.provider.cache_stopped_nodes"),"\nand ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.teardown_cluster.workers_only")),(0,l.mdx)("table",{parentName:"li"},(0,l.mdx)("thead",{parentName:"table"},(0,l.mdx)("tr",{parentName:"thead"},(0,l.mdx)("th",{parentName:"tr",align:null},"cache_stopped_nodes"),(0,l.mdx)("th",{parentName:"tr",align:null},"workers_only"),(0,l.mdx)("th",{parentName:"tr",align:null},"behavior"))),(0,l.mdx)("tbody",{parentName:"table"},(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"All nodes are terminated")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"Keeps head node running and terminates only worker node")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"Keeps both head node and worker node and stops both of them")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"Keeps both head node and worker node and stops only worker node"))))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Keep ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.cluster.min_workers")," worker nodes\nand delete the rest of the worker nodes"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.teardown_cluster.keep_min_workers=true\n")))),(0,l.mdx)("p",null,"Additionally, you can configure how to create or update the cluster:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Default config: run setup commands, restart Ray and use\nthe config cache if available"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.create_update_cluster.no_restart=false\nhydra.launcher.create_update_cluster.restart_only=false\nhydra.launcher.create_update_cluster.no_config_cache=false\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Skip restarting Ray services when updating the cluster config"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.create_update_cluster.no_restart=true\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Skip running setup commands and only restart Ray (cannot be used with\n",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.create_update_cluster.no_restart"),")"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.create_update_cluster.restart_only=true\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Fully resolve all environment settings from the cloud provider again"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.create_update_cluster.no_config_cache=true\n")))),(0,l.mdx)("h5",{id:"configure-ray-logging"},"Configure Ray Logging"),(0,l.mdx)("p",null,"You can manage Ray specific logging by configuring the flags provided by the plugin:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Default config: use minimal verbosity and automatically\ndetect whether to use pretty-print and color mode"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},'hydra.launcher.logging.log_style="auto"\nhydra.launcher.logging.color_mode="auto"\nhydra.launcher.logging.verbosity=0\n'))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Disable pretty-print"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},'hydra.launcher.logging.log_style="record"\n'))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Disable color mode"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},'hydra.launcher.logging.color_mode="false"\n'))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Increase Ray logging verbosity"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.logging.verbosity=3\n")))),(0,l.mdx)("h3",{id:"ray-launcher"},(0,l.mdx)("inlineCode",{parentName:"h3"},"ray")," launcher"),(0,l.mdx)("p",null,(0,l.mdx)("inlineCode",{parentName:"p"},"ray")," launcher lets you launch application on your ray cluster or local machine. You can easily config how your jobs are executed by changing ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray")," launcher's configuration here\n",(0,l.mdx)("inlineCode",{parentName:"p"},"~/hydra/plugins/hydra_ray_launcher/hydra_plugins/hydra_ray_launcher/conf/hydra/launcher/ray.yaml")),(0,l.mdx)("p",null," The ",(0,l.mdx)(i.A,{to:"plugins/hydra_ray_launcher/examples/simple",mdxType:"GithubLink"},"example application")," starts a new ray cluster."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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")),(0,l.mdx)("p",null,"You can run the example application on your existing ray cluster as well by overriding ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.init.address"),":"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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")),(0,l.mdx)("h3",{id:"configure-rayinit-and-rayremote"},"Configure ",(0,l.mdx)("inlineCode",{parentName:"h3"},"ray.init()")," and ",(0,l.mdx)("inlineCode",{parentName:"h3"},"ray.remote()")),(0,l.mdx)("p",null,"Ray launcher is built on top of ",(0,l.mdx)("a",{parentName:"p",href:"https://docs.ray.io/en/master/package-ref.html?highlight=ray.remote#ray-init"},(0,l.mdx)("inlineCode",{parentName:"a"},"ray.init()")),"\nand ",(0,l.mdx)("a",{parentName:"p",href:"https://docs.ray.io/en/master/package-ref.html?highlight=ray.remote#ray-remote"},(0,l.mdx)("inlineCode",{parentName:"a"},"ray.remote()")),".\nYou can configure ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray")," by overriding ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.init")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.remote"),".\nCheck out an ",(0,l.mdx)(i.A,{to:"plugins/hydra_ray_launcher/examples/simple/config.yaml",mdxType:"GithubLink"},"example config"),"."))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/13a26e00.7105d0f7.js b/assets/js/13a26e00.7105d0f7.js new file mode 100644 index 0000000000..05dd52ddce --- /dev/null +++ b/assets/js/13a26e00.7105d0f7.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[6297],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>m,MDXProvider:()=>c,mdx:()=>y,useMDXComponents:()=>s,withMDXComponents:()=>p});var r=a(96540);function t(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function l(){return l=Object.assign||function(e){for(var n=1;n=0||(t[a]=e[a]);return t}(e,n);if(Object.getOwnPropertySymbols){var l=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(t[a]=e[a])}return t}var m=r.createContext({}),p=function(e){return function(n){var a=s(n.components);return r.createElement(e,l({},n,{components:a}))}},s=function(e){var n=r.useContext(m),a=n;return e&&(a="function"==typeof e?e(n):o(o({},n),e)),a},c=function(e){var n=s(e.components);return r.createElement(m.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},h=r.forwardRef((function(e,n){var a=e.components,t=e.mdxType,l=e.originalType,i=e.parentName,m=d(e,["components","mdxType","originalType","parentName"]),p=s(a),c=t,h=p["".concat(i,".").concat(c)]||p[c]||u[c]||l;return a?r.createElement(h,o(o({ref:n},m),{},{components:a})):r.createElement(h,o({ref:n},m))}));function y(e,n){var a=arguments,t=n&&n.mdxType;if("string"==typeof e||t){var l=a.length,i=new Array(l);i[0]=h;var o={};for(var d in n)hasOwnProperty.call(n,d)&&(o[d]=n[d]);o.originalType=e,o.mdxType="string"==typeof e?e:t,i[1]=o;for(var m=2;m{a.d(n,{A:()=>d,C:()=>m});var r=a(58168),t=a(96540),l=a(75489),i=a(44586),o=a(74098);function d(e){return t.createElement(l.default,(0,r.A)({},e,{to:(n=e.to,d=(0,o.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(a=null==d?void 0:d.name)?a:"current"]+n),target:"_blank"}));var n,a,d}function m(e){var n,a=null!=(n=e.text)?n:"Example (Click Here)";return t.createElement(d,e,t.createElement("span",null,"\xa0"),t.createElement("img",{src:"https://img.shields.io/badge/-"+a+"-informational",alt:"Example (Click Here)"}))}},84850:(e,n,a)=>{a.r(n),a.d(n,{contentTitle:()=>m,default:()=>u,frontMatter:()=>d,metadata:()=>p,toc:()=>s});var r=a(58168),t=a(98587),l=(a(96540),a(15680)),i=a(49595),o=["components"],d={id:"ray_launcher",title:"Ray Launcher plugin",sidebar_label:"Ray Launcher plugin"},m=void 0,p={unversionedId:"plugins/ray_launcher",id:"version-1.1/plugins/ray_launcher",title:"Ray Launcher plugin",description:"PyPI",source:"@site/versioned_docs/version-1.1/plugins/ray_launcher.md",sourceDirName:"plugins",slug:"/plugins/ray_launcher",permalink:"/docs/1.1/plugins/ray_launcher",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/plugins/ray_launcher.md",tags:[],version:"1.1",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"ray_launcher",title:"Ray Launcher plugin",sidebar_label:"Ray Launcher plugin"},sidebar:"version-1.1/docs",previous:{title:"Joblib Launcher plugin",permalink:"/docs/1.1/plugins/joblib_launcher"},next:{title:"RQ Launcher plugin",permalink:"/docs/1.1/plugins/rq_launcher"}},s=[{value:"Installation",id:"installation",children:[],level:3},{value:"Usage",id:"usage",children:[],level:3},{value:"ray_aws launcher",id:"ray_aws-launcher",children:[{value:"Examples",id:"examples",children:[{value:"Manage Cluster LifeCycle",id:"manage-cluster-lifecycle",children:[],level:5},{value:"Configure Ray Logging",id:"configure-ray-logging",children:[],level:5}],level:4}],level:3},{value:"ray launcher",id:"ray-launcher",children:[],level:3},{value:"Configure ray.init() and ray.remote()",id:"configure-rayinit-and-rayremote",children:[],level:3}],c={toc:s};function u(e){var n=e.components,a=(0,t.A)(e,o);return(0,l.mdx)("wrapper",(0,r.A)({},c,a,{components:n,mdxType:"MDXLayout"}),(0,l.mdx)("p",null,(0,l.mdx)("a",{parentName:"p",href:"https://pypi.org/project/hydra-ray-launcher/"},(0,l.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/v/hydra-ray-launcher",alt:"PyPI"})),"\n",(0,l.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/l/hydra-ray-launcher",alt:"PyPI - License"}),"\n",(0,l.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/pyversions/hydra-ray-launcher",alt:"PyPI - Python Version"}),"\n",(0,l.mdx)("a",{parentName:"p",href:"https://pypistats.org/packages/hydra-ray-launcher"},(0,l.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/dm/hydra-ray-launcher.svg",alt:"PyPI - Downloads"})),(0,l.mdx)(i.C,{text:"Example application",to:"plugins/hydra_ray_launcher/examples",mdxType:"ExampleGithubLink"}),(0,l.mdx)(i.C,{text:"Plugin source",to:"plugins/hydra_ray_launcher",mdxType:"ExampleGithubLink"})),(0,l.mdx)("p",null,"The Ray Launcher plugin provides 2 launchers: ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray_aws")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray"),".\n",(0,l.mdx)("inlineCode",{parentName:"p"},"ray_aws")," launches jobs remotely on AWS and is built on top of ",(0,l.mdx)("a",{parentName:"p",href:"https://docs.ray.io/en/releases-1.3.0/cluster/sdk.html"},"ray autoscaler sdk"),". ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray")," launches jobs on your local machine or existing ray cluster. "),(0,l.mdx)("h3",{id:"installation"},"Installation"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ pip install hydra-ray-launcher --upgrade\n")),(0,l.mdx)("h3",{id:"usage"},"Usage"),(0,l.mdx)("p",null,"Once installed, add ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra/launcher=ray_aws")," or ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra/launcher=ray")," to your command line. Alternatively, override ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra/launcher")," in your config:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - override hydra/launcher: ray_aws\n")),(0,l.mdx)("p",null,"There are several standard approaches for configuring plugins. Check ",(0,l.mdx)("a",{parentName:"p",href:"/docs/1.1/patterns/configuring_plugins"},"this page")," for more information."),(0,l.mdx)("h3",{id:"ray_aws-launcher"},(0,l.mdx)("inlineCode",{parentName:"h3"},"ray_aws")," launcher"),(0,l.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,l.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,l.mdx)("h5",{parentName:"div"},(0,l.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,l.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,l.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,l.mdx)("div",{parentName:"div",className:"admonition-content"},(0,l.mdx)("p",{parentName:"div"},(0,l.mdx)("inlineCode",{parentName:"p"},"ray_aws")," launcher is built on top of ray's ",(0,l.mdx)("a",{parentName:"p",href:"https://docs.ray.io/en/releases-1.3.0/cluster/sdk.html"},"autoscaler sdk"),". To get started, you need to\n",(0,l.mdx)("a",{parentName:"p",href:"https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html"},"config your AWS credentials"),".\n",(0,l.mdx)("inlineCode",{parentName:"p"},"ray autoscaler sdk")," expects your AWS credentials have certain permissions for ",(0,l.mdx)("a",{parentName:"p",href:"https://aws.amazon.com/ec2"},(0,l.mdx)("inlineCode",{parentName:"a"},"EC2"))," and ",(0,l.mdx)("a",{parentName:"p",href:"https://aws.amazon.com/iam"},(0,l.mdx)("inlineCode",{parentName:"a"},"IAM")),". Read ",(0,l.mdx)("a",{parentName:"p",href:"https://github.com/ray-project/ray/issues/9327"},"this")," for more information."))),(0,l.mdx)("p",null,(0,l.mdx)("inlineCode",{parentName:"p"},"ray autoscaler sdk")," expects a configuration for the EC2 cluster; we've schematized the configs in ",(0,l.mdx)(i.A,{to:"plugins/hydra_ray_launcher/hydra_plugins/hydra_ray_launcher/_config.py",mdxType:"GithubLink"},"here")),(0,l.mdx)("details",null,(0,l.mdx)("summary",null,"Discover ray_aws launcher's config"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ python my_app.py hydra/launcher=ray_aws --cfg hydra -p hydra.launcher\n# @package hydra.launcher\n_target_: hydra_plugins.hydra_ray_launcher.ray_aws_launcher.RayAWSLauncher\nenv_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.1.0.dev3\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\nray:\n init:\n address: null\n remote: {}\n cluster:\n cluster_name: default\n min_workers: 0\n max_workers: 1\n initial_workers: 0\n autoscaling_mode: default\n target_utilization_fraction: 0.8\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 head_node:\n InstanceType: m5.large\n ImageId: ami-008d8ed4bd7dc2485\n worker_nodes:\n InstanceType: m5.large\n ImageId: ami-008d8ed4bd7dc2485\n file_mounts: {}\n initialization_commands: []\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\n --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\nstop_cluster: true\nsync_up:\n source_dir: null\n target_dir: null\n include: []\n exclude: []\nsync_down:\n source_dir: null\n target_dir: null\n include: []\n exclude: []\nlogging:\n log_style: auto\n color_mode: auto\n verbosity: 0\ncreate_update_cluster:\n no_restart: false\n restart_only: false\n no_config_cache: false\nteardown_cluster:\n workers_only: false\n keep_min_workers: false\n"))),(0,l.mdx)("h4",{id:"examples"},"Examples"),(0,l.mdx)("p",null,"The following examples can be found ",(0,l.mdx)(i.A,{to:"plugins/hydra_ray_launcher/examples",mdxType:"GithubLink"},"here"),"."),(0,l.mdx)("details",null,(0,l.mdx)("summary",null,"Simple app"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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\nCluster: default\n...\nINFO 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)\nDestroying cluster. Confirm [y/N]: y [automatic, due to --yes]\n...\nNo nodes remaining.\n\n"))),(0,l.mdx)("details",null,(0,l.mdx)("summary",null,"Upload & Download from remote cluster"),(0,l.mdx)("p",null,"If your application is dependent on multiple modules, you can configure ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.sync_up")," to upload dependency modules to the remote cluster.\nYou can also configure ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.sync_down")," to download output from remote cluster if needed. This functionality is built on top of ",(0,l.mdx)("inlineCode",{parentName:"p"},"rsync"),", ",(0,l.mdx)("inlineCode",{parentName:"p"},"include")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"exclude")," is consistent with how it works in ",(0,l.mdx)("inlineCode",{parentName:"p"},"rsync"),"."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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\nCluster: default\n...\nINFO 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\nLoaded cached provider configuration\n...\n[HYDRA] Output: receiving file list ... done\n16-32-25/\n16-32-25/0/\n16-32-25/0/checkpoint/\n16-32-25/0/checkpoint/checkpoint_1.pt\n16-32-25/1/\n16-32-25/1/checkpoint/\n16-32-25/1/checkpoint/checkpoint_2.pt\n16-32-25/2/\n16-32-25/2/checkpoint/\n16-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)\nDestroying cluster. Confirm [y/N]: y [automatic, due to --yes]\n...\nNo nodes remaining.\n\n"))),(0,l.mdx)("h5",{id:"manage-cluster-lifecycle"},"Manage Cluster LifeCycle"),(0,l.mdx)("p",null,"You can manage the Ray EC2 cluster lifecycle by configuring the flags provided by the plugin:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Default setting (no need to specify on commandline): delete cluster after job finishes remotely:"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.stop_cluster=true\nhydra.launcher.ray.cluster.provider.cache_stopped_nodes=false\nhydra.launcher.teardown_cluster.workers_only=false\nhydra.launcher.teardown_cluster.keep_min_workers=false\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Keep cluster running after jobs finishes remotely"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.stop_cluster=false\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Power off EC2 instances and control node termination using ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.cluster.provider.cache_stopped_nodes"),"\nand ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.teardown_cluster.workers_only")),(0,l.mdx)("table",{parentName:"li"},(0,l.mdx)("thead",{parentName:"table"},(0,l.mdx)("tr",{parentName:"thead"},(0,l.mdx)("th",{parentName:"tr",align:null},"cache_stopped_nodes"),(0,l.mdx)("th",{parentName:"tr",align:null},"workers_only"),(0,l.mdx)("th",{parentName:"tr",align:null},"behavior"))),(0,l.mdx)("tbody",{parentName:"table"},(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"All nodes are terminated")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"Keeps head node running and terminates only worker node")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"Keeps both head node and worker node and stops both of them")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"Keeps both head node and worker node and stops only worker node"))))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Keep ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.cluster.min_workers")," worker nodes\nand delete the rest of the worker nodes"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.teardown_cluster.keep_min_workers=true\n")))),(0,l.mdx)("p",null,"Additionally, you can configure how to create or update the cluster:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Default config: run setup commands, restart Ray and use\nthe config cache if available"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.create_update_cluster.no_restart=false\nhydra.launcher.create_update_cluster.restart_only=false\nhydra.launcher.create_update_cluster.no_config_cache=false\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Skip restarting Ray services when updating the cluster config"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.create_update_cluster.no_restart=true\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Skip running setup commands and only restart Ray (cannot be used with\n",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.create_update_cluster.no_restart"),")"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.create_update_cluster.restart_only=true\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Fully resolve all environment settings from the cloud provider again"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.create_update_cluster.no_config_cache=true\n")))),(0,l.mdx)("h5",{id:"configure-ray-logging"},"Configure Ray Logging"),(0,l.mdx)("p",null,"You can manage Ray specific logging by configuring the flags provided by the plugin:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Default config: use minimal verbosity and automatically\ndetect whether to use pretty-print and color mode"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},'hydra.launcher.logging.log_style="auto"\nhydra.launcher.logging.color_mode="auto"\nhydra.launcher.logging.verbosity=0\n'))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Disable pretty-print"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},'hydra.launcher.logging.log_style="record"\n'))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Disable color mode"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},'hydra.launcher.logging.color_mode="false"\n'))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Increase Ray logging verbosity"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.logging.verbosity=3\n")))),(0,l.mdx)("h3",{id:"ray-launcher"},(0,l.mdx)("inlineCode",{parentName:"h3"},"ray")," launcher"),(0,l.mdx)("p",null,(0,l.mdx)("inlineCode",{parentName:"p"},"ray")," launcher lets you launch application on your ray cluster or local machine. You can easily config how your jobs are executed by changing ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray")," launcher's configuration here\n",(0,l.mdx)("inlineCode",{parentName:"p"},"~/hydra/plugins/hydra_ray_launcher/hydra_plugins/hydra_ray_launcher/conf/hydra/launcher/ray.yaml")),(0,l.mdx)("p",null," The ",(0,l.mdx)(i.A,{to:"plugins/hydra_ray_launcher/examples/simple",mdxType:"GithubLink"},"example application")," starts a new ray cluster."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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")),(0,l.mdx)("p",null,"You can run the example application on your existing ray cluster as well by overriding ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.init.address"),":"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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")),(0,l.mdx)("h3",{id:"configure-rayinit-and-rayremote"},"Configure ",(0,l.mdx)("inlineCode",{parentName:"h3"},"ray.init()")," and ",(0,l.mdx)("inlineCode",{parentName:"h3"},"ray.remote()")),(0,l.mdx)("p",null,"Ray launcher is built on top of ",(0,l.mdx)("a",{parentName:"p",href:"https://docs.ray.io/en/master/package-ref.html?highlight=ray.remote#ray-init"},(0,l.mdx)("inlineCode",{parentName:"a"},"ray.init()")),"\nand ",(0,l.mdx)("a",{parentName:"p",href:"https://docs.ray.io/en/master/package-ref.html?highlight=ray.remote#ray-remote"},(0,l.mdx)("inlineCode",{parentName:"a"},"ray.remote()")),".\nYou can configure ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray")," by overriding ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.init")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.remote"),".\nCheck out an ",(0,l.mdx)(i.A,{to:"plugins/hydra_ray_launcher/examples/simple/config.yaml",mdxType:"GithubLink"},"example config"),"."))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/14173c40.7019386c.js b/assets/js/14173c40.7019386c.js new file mode 100644 index 0000000000..7bbe3f6462 --- /dev/null +++ b/assets/js/14173c40.7019386c.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[4210],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>m,MDXProvider:()=>s,mdx:()=>g,useMDXComponents:()=>p,withMDXComponents:()=>c});var r=a(96540);function t(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(t[a]=e[a]);return t}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(t[a]=e[a])}return t}var m=r.createContext({}),c=function(e){return function(n){var a=p(n.components);return r.createElement(e,i({},n,{components:a}))}},p=function(e){var n=r.useContext(m),a=n;return e&&(a="function"==typeof e?e(n):l(l({},n),e)),a},s=function(e){var n=p(e.components);return r.createElement(m.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},f=r.forwardRef((function(e,n){var a=e.components,t=e.mdxType,i=e.originalType,o=e.parentName,m=d(e,["components","mdxType","originalType","parentName"]),c=p(a),s=t,f=c["".concat(o,".").concat(s)]||c[s]||u[s]||i;return a?r.createElement(f,l(l({ref:n},m),{},{components:a})):r.createElement(f,l({ref:n},m))}));function g(e,n){var a=arguments,t=n&&n.mdxType;if("string"==typeof e||t){var i=a.length,o=new Array(i);o[0]=f;var l={};for(var d in n)hasOwnProperty.call(n,d)&&(l[d]=n[d]);l.originalType=e,l.mdxType="string"==typeof e?e:t,o[1]=l;for(var m=2;m{a.r(n),a.d(n,{contentTitle:()=>d,default:()=>s,frontMatter:()=>l,metadata:()=>m,toc:()=>c});var r=a(58168),t=a(98587),i=(a(96540),a(15680)),o=["components"],l={id:"hydra-command-line-flags",title:"Hydra's command line flags"},d=void 0,m={unversionedId:"advanced/hydra-command-line-flags",id:"advanced/hydra-command-line-flags",title:"Hydra's command line flags",description:"Hydra is using the command line for two things:",source:"@site/docs/advanced/hydra-command-line-flags.md",sourceDirName:"advanced",slug:"/advanced/hydra-command-line-flags",permalink:"/docs/advanced/hydra-command-line-flags",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/advanced/hydra-command-line-flags.md",tags:[],version:"current",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"hydra-command-line-flags",title:"Hydra's command line flags"},sidebar:"docs",previous:{title:"Terminology",permalink:"/docs/advanced/terminology"},next:{title:"Basic Override syntax",permalink:"/docs/advanced/override_grammar/basic"}},c=[],p={toc:c};function s(e){var n=e.components,a=(0,t.A)(e,o);return(0,i.mdx)("wrapper",(0,r.A)({},p,a,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Hydra is using the command line for two things:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"Controlling Hydra"),(0,i.mdx)("li",{parentName:"ul"},"Configuring your application (See ",(0,i.mdx)("a",{parentName:"li",href:"/docs/advanced/override_grammar/basic"},"Override Grammar"),")")),(0,i.mdx)("p",null,"Arguments prefixed by - or -- control Hydra; the rest are used to configure the application."),(0,i.mdx)("p",null,"Information about Hydra:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--hydra-help"),": Shows Hydra specific flags"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--version"),": Show Hydra's version and exit")),(0,i.mdx)("p",null,"Information provided by the Hydra app:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--help,-h"),": Shows the application's help. This can be ",(0,i.mdx)("a",{parentName:"li",href:"/docs/configure_hydra/app_help"},"customized"),".")),(0,i.mdx)("p",null,"Debugging assistance:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--cfg,-c"),": Show config instead of running. Takes as parameter one of ",(0,i.mdx)("inlineCode",{parentName:"li"},"job"),", ",(0,i.mdx)("inlineCode",{parentName:"li"},"hydra")," or ",(0,i.mdx)("inlineCode",{parentName:"li"},"all"),"."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--resolve"),": Used in conjunction with the ",(0,i.mdx)("inlineCode",{parentName:"li"},"--cfg")," flag; resolve interpolations in the config before printing it."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--package,-p"),": Used in conjunction with --cfg to select a specific config package to show."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--info,-i"),": Print Hydra information. This includes installed plugins, Config Search Path, Defaults List, generated config and more.")),(0,i.mdx)("p",null,"Running Hydra applications:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--run,-r"),": Run is the default mode and is not normally needed."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--multirun,-m"),": Run multiple jobs with the configured launcher and sweeper. See ",(0,i.mdx)("a",{parentName:"li",href:"/docs/tutorials/basic/running_your_app/multi-run"},"Multi-run"),".",(0,i.mdx)("br",null),(0,i.mdx)("br",null)),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--config-path,-cp"),": Overrides the ",(0,i.mdx)("inlineCode",{parentName:"li"},"config_path")," specified in ",(0,i.mdx)("inlineCode",{parentName:"li"},"hydra.main()"),". The ",(0,i.mdx)("inlineCode",{parentName:"li"},"config_path")," is absolute or relative to the Python file declaring ",(0,i.mdx)("inlineCode",{parentName:"li"},"@hydra.main()"),"."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--config-name,-cn"),": Overrides the ",(0,i.mdx)("inlineCode",{parentName:"li"},"config_name")," specified in ",(0,i.mdx)("inlineCode",{parentName:"li"},"hydra.main()"),"."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--config-dir,-cd"),": Adds an additional config directory to the ",(0,i.mdx)("a",{parentName:"li",href:"/docs/advanced/search_path"},"config search path"),".",(0,i.mdx)("br",{parentName:"li"}),"This is useful for installed apps that want to allow their users to provide additional configs.")),(0,i.mdx)("p",null,"Misc:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--shell-completion,-sc"),": Install or Uninstall ",(0,i.mdx)("a",{parentName:"li",href:"/docs/tutorials/basic/running_your_app/tab_completion"},"shell tab completion"),".")))}s.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/14173c40.ad4a53ce.js b/assets/js/14173c40.ad4a53ce.js deleted file mode 100644 index cce3888a10..0000000000 --- a/assets/js/14173c40.ad4a53ce.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[4210],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>m,MDXProvider:()=>p,mdx:()=>g,useMDXComponents:()=>s,withMDXComponents:()=>c});var r=a(96540);function t(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(t[a]=e[a]);return t}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(t[a]=e[a])}return t}var m=r.createContext({}),c=function(e){return function(n){var a=s(n.components);return r.createElement(e,i({},n,{components:a}))}},s=function(e){var n=r.useContext(m),a=n;return e&&(a="function"==typeof e?e(n):l(l({},n),e)),a},p=function(e){var n=s(e.components);return r.createElement(m.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},f=r.forwardRef((function(e,n){var a=e.components,t=e.mdxType,i=e.originalType,o=e.parentName,m=d(e,["components","mdxType","originalType","parentName"]),c=s(a),p=t,f=c["".concat(o,".").concat(p)]||c[p]||u[p]||i;return a?r.createElement(f,l(l({ref:n},m),{},{components:a})):r.createElement(f,l({ref:n},m))}));function g(e,n){var a=arguments,t=n&&n.mdxType;if("string"==typeof e||t){var i=a.length,o=new Array(i);o[0]=f;var l={};for(var d in n)hasOwnProperty.call(n,d)&&(l[d]=n[d]);l.originalType=e,l.mdxType="string"==typeof e?e:t,o[1]=l;for(var m=2;m{a.r(n),a.d(n,{contentTitle:()=>d,default:()=>p,frontMatter:()=>l,metadata:()=>m,toc:()=>c});var r=a(58168),t=a(98587),i=(a(96540),a(15680)),o=["components"],l={id:"hydra-command-line-flags",title:"Hydra's command line flags"},d=void 0,m={unversionedId:"advanced/hydra-command-line-flags",id:"advanced/hydra-command-line-flags",title:"Hydra's command line flags",description:"Hydra is using the command line for two things:",source:"@site/docs/advanced/hydra-command-line-flags.md",sourceDirName:"advanced",slug:"/advanced/hydra-command-line-flags",permalink:"/docs/advanced/hydra-command-line-flags",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/advanced/hydra-command-line-flags.md",tags:[],version:"current",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"hydra-command-line-flags",title:"Hydra's command line flags"},sidebar:"docs",previous:{title:"Terminology",permalink:"/docs/advanced/terminology"},next:{title:"Basic Override syntax",permalink:"/docs/advanced/override_grammar/basic"}},c=[],s={toc:c};function p(e){var n=e.components,a=(0,t.A)(e,o);return(0,i.mdx)("wrapper",(0,r.A)({},s,a,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Hydra is using the command line for two things:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"Controlling Hydra"),(0,i.mdx)("li",{parentName:"ul"},"Configuring your application (See ",(0,i.mdx)("a",{parentName:"li",href:"/docs/advanced/override_grammar/basic"},"Override Grammar"),")")),(0,i.mdx)("p",null,"Arguments prefixed by - or -- control Hydra; the rest are used to configure the application."),(0,i.mdx)("p",null,"Information about Hydra:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--hydra-help"),": Shows Hydra specific flags"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--version"),": Show Hydra's version and exit")),(0,i.mdx)("p",null,"Information provided by the Hydra app:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--help,-h"),": Shows the application's help. This can be ",(0,i.mdx)("a",{parentName:"li",href:"/docs/configure_hydra/app_help"},"customized"),".")),(0,i.mdx)("p",null,"Debugging assistance:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--cfg,-c"),": Show config instead of running. Takes as parameter one of ",(0,i.mdx)("inlineCode",{parentName:"li"},"job"),", ",(0,i.mdx)("inlineCode",{parentName:"li"},"hydra")," or ",(0,i.mdx)("inlineCode",{parentName:"li"},"all"),"."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--resolve"),": Used in conjunction with the ",(0,i.mdx)("inlineCode",{parentName:"li"},"--cfg")," flag; resolve interpolations in the config before printing it."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--package,-p"),": Used in conjunction with --cfg to select a specific config package to show."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--info,-i"),": Print Hydra information. This includes installed plugins, Config Search Path, Defaults List, generated config and more.")),(0,i.mdx)("p",null,"Running Hydra applications:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--run,-r"),": Run is the default mode and is not normally needed."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--multirun,-m"),": Run multiple jobs with the configured launcher and sweeper. See ",(0,i.mdx)("a",{parentName:"li",href:"/docs/tutorials/basic/running_your_app/multi-run"},"Multi-run"),".",(0,i.mdx)("br",null),(0,i.mdx)("br",null)),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--config-path,-cp"),": Overrides the ",(0,i.mdx)("inlineCode",{parentName:"li"},"config_path")," specified in ",(0,i.mdx)("inlineCode",{parentName:"li"},"hydra.main()"),". The ",(0,i.mdx)("inlineCode",{parentName:"li"},"config_path")," is absolute or relative to the Python file declaring ",(0,i.mdx)("inlineCode",{parentName:"li"},"@hydra.main()"),"."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--config-name,-cn"),": Overrides the ",(0,i.mdx)("inlineCode",{parentName:"li"},"config_name")," specified in ",(0,i.mdx)("inlineCode",{parentName:"li"},"hydra.main()"),"."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--config-dir,-cd"),": Adds an additional config directory to the ",(0,i.mdx)("a",{parentName:"li",href:"/docs/advanced/search_path"},"config search path"),".",(0,i.mdx)("br",{parentName:"li"}),"This is useful for installed apps that want to allow their users to provide additional configs.")),(0,i.mdx)("p",null,"Misc:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--shell-completion,-sc"),": Install or Uninstall ",(0,i.mdx)("a",{parentName:"li",href:"/docs/tutorials/basic/running_your_app/tab_completion"},"shell tab completion"),".")))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/141a01e8.29148033.js b/assets/js/141a01e8.29148033.js deleted file mode 100644 index 04ce927be2..0000000000 --- a/assets/js/141a01e8.29148033.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[20],{15680:(e,a,n)=>{n.r(a),n.d(a,{MDXContext:()=>m,MDXProvider:()=>p,mdx:()=>f,useMDXComponents:()=>c,withMDXComponents:()=>d});var t=n(96540);function r(e,a,n){return a in e?Object.defineProperty(e,a,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[a]=n,e}function l(){return l=Object.assign||function(e){for(var a=1;a=0||(r[n]=e[n]);return r}(e,a);if(Object.getOwnPropertySymbols){var l=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var m=t.createContext({}),d=function(e){return function(a){var n=c(a.components);return t.createElement(e,l({},a,{components:n}))}},c=function(e){var a=t.useContext(m),n=a;return e&&(n="function"==typeof e?e(a):o(o({},a),e)),n},p=function(e){var a=c(e.components);return t.createElement(m.Provider,{value:a},e.children)},g={inlineCode:"code",wrapper:function(e){var a=e.children;return t.createElement(t.Fragment,{},a)}},u=t.forwardRef((function(e,a){var n=e.components,r=e.mdxType,l=e.originalType,i=e.parentName,m=s(e,["components","mdxType","originalType","parentName"]),d=c(n),p=r,u=d["".concat(i,".").concat(p)]||d[p]||g[p]||l;return n?t.createElement(u,o(o({ref:a},m),{},{components:n})):t.createElement(u,o({ref:a},m))}));function f(e,a){var n=arguments,r=a&&a.mdxType;if("string"==typeof e||r){var l=n.length,i=new Array(l);i[0]=u;var o={};for(var s in a)hasOwnProperty.call(a,s)&&(o[s]=a[s]);o.originalType=e,o.mdxType="string"==typeof e?e:r,i[1]=o;for(var m=2;m{n.r(a),n.d(a,{contentTitle:()=>s,default:()=>p,frontMatter:()=>o,metadata:()=>m,toc:()=>d});var t=n(58168),r=n(98587),l=(n(96540),n(15680)),i=["components"],o={id:"overriding_packages",title:"Packages"},s=void 0,m={unversionedId:"advanced/overriding_packages",id:"version-1.1/advanced/overriding_packages",title:"Packages",description:"The package determines where the content of each input config is placed in the output config.",source:"@site/versioned_docs/version-1.1/advanced/overriding_packages.md",sourceDirName:"advanced",slug:"/advanced/overriding_packages",permalink:"/docs/1.1/advanced/overriding_packages",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/advanced/overriding_packages.md",tags:[],version:"1.1",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"overriding_packages",title:"Packages"},sidebar:"version-1.1/docs",previous:{title:"The Defaults List",permalink:"/docs/1.1/advanced/defaults_list"},next:{title:"Overview",permalink:"/docs/1.1/advanced/instantiate_objects/overview"}},d=[{value:"An example using only default packages",id:"an-example-using-only-default-packages",children:[],level:3},{value:"Overriding packages using the Defaults List",id:"overriding-packages-using-the-defaults-list",children:[{value:"Default List package keywords",id:"default-list-package-keywords",children:[{value:"Absolute keywords:",id:"absolute-keywords",children:[],level:5}],level:4}],level:3},{value:"Overriding the package via the package directive",id:"overriding-the-package-via-the-package-directive",children:[],level:3},{value:"Using a config group more than once",id:"using-a-config-group-more-than-once",children:[],level:3}],c={toc:d};function p(e){var a=e.components,n=(0,r.A)(e,i);return(0,l.mdx)("wrapper",(0,t.A)({},c,n,{components:a,mdxType:"MDXLayout"}),(0,l.mdx)("p",null,"The package determines where the content of each input config is placed in the output config.\nThe default package of an input config is derived from its Config Group. e.g. The default package of ",(0,l.mdx)("inlineCode",{parentName:"p"},"server/db/mysql.yaml")," is ",(0,l.mdx)("inlineCode",{parentName:"p"},"server.db"),"."),(0,l.mdx)("p",null,"The default package can be overridden ",(0,l.mdx)("a",{parentName:"p",href:"#overriding-packages-using-the-defaults-list"},"in the Defaults List"),"\nor via a ",(0,l.mdx)("a",{parentName:"p",href:"#overriding-the-package-via-the-package-directive"},"Package Directive")," at the top of the config file.\nChanging the package of a config can be useful when using a config from another library, or when using the same\nconfig group twice in the same app."),(0,l.mdx)("p",null,"The priority for determining the final package for a config is as follows:"),(0,l.mdx)("ol",null,(0,l.mdx)("li",{parentName:"ol"},"The package specified in the Defaults List (relative to the package of the including config)"),(0,l.mdx)("li",{parentName:"ol"},"The package specified in the Package Directive (absolute)"),(0,l.mdx)("li",{parentName:"ol"},"The default package")),(0,l.mdx)("p",null,"We will use the following configs in the examples below:"),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--4"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - server/apache\n\ndebug: false\n\n\n\n"))),(0,l.mdx)("div",{className:"col col--4"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/apache.yaml"',title:'"server/apache.yaml"'},"defaults:\n - db: mysql\n\nname: apache\n\n\n\n"))),(0,l.mdx)("div",{className:"col col--4"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/db/mysql.yaml"',title:'"server/db/mysql.yaml"'},"name: mysql\n")),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/db/sqlite.yaml"',title:'"server/db/sqlite.yaml"'},"name: sqlite\n")))),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Config directory structure"',title:'"Config',directory:!0,'structure"':!0},"\u251c\u2500\u2500 server\n\u2502 \u251c\u2500\u2500 db\n\u2502 \u2502 \u251c\u2500\u2500 mysql.yaml\n\u2502 \u2502 \u2514\u2500\u2500 sqlite.yaml\n\u2502 \u2514\u2500\u2500 apache.yaml\n\u2514\u2500\u2500 config.yaml\n")),(0,l.mdx)("h3",{id:"an-example-using-only-default-packages"},"An example using only default packages"),(0,l.mdx)("p",null,"The default package of ",(0,l.mdx)("em",{parentName:"p"},"config.yaml")," is the global package, of ",(0,l.mdx)("em",{parentName:"p"},"server/apache.yaml")," is ",(0,l.mdx)("em",{parentName:"p"},"server")," and of ",(0,l.mdx)("em",{parentName:"p"},"server/db/mysql.yaml")," is ",(0,l.mdx)("em",{parentName:"p"},"server.db"),". "),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py" {1-2}',title:'"$',python:!0,'my_app.py"':!0,"{1-2}":!0},"server:\n db:\n name: mysql\n name: apache\ndebug: false\n")))),(0,l.mdx)("h3",{id:"overriding-packages-using-the-defaults-list"},"Overriding packages using the Defaults List"),(0,l.mdx)("p",null,"By default, packages specified in the Defaults List are relative to the package of containing config.\nAs a consequence, overriding a package relocates the entire subtree. "),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--4"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {2}',title:'"config.yaml"',"{2}":!0},"defaults:\n - server/apache@admin\n\ndebug: false\n\n"))),(0,l.mdx)("div",{className:"col col--4"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/apache.yaml" {2}',title:'"server/apache.yaml"',"{2}":!0},"defaults:\n - db@backup: mysql\n\nname: apache\n\n"))),(0,l.mdx)("div",{className:"col col--4"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Output config" {1-4}',title:'"Output','config"':!0,"{1-4}":!0},"admin:\n backup:\n name: mysql\n name: apache\ndebug: false\n")))),(0,l.mdx)("p",null,"Note that content of ",(0,l.mdx)("em",{parentName:"p"},"server/apache.yaml")," is relocated to ",(0,l.mdx)("em",{parentName:"p"},"admin"),"\nand the content of ",(0,l.mdx)("em",{parentName:"p"},"server/db/mysql.yaml")," to ",(0,l.mdx)("em",{parentName:"p"},"admin.backup"),"."),(0,l.mdx)("h4",{id:"default-list-package-keywords"},"Default List package keywords"),(0,l.mdx)("p",null,"We will use this example, replacing ",(0,l.mdx)("em",{parentName:"p"},"<@PACKAGE>")," to demonstrate different cases:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config_group/config.yaml"',title:'"config_group/config.yaml"'},"defaults:\n - /server/db<@PACKAGE>: mysql\n")),(0,l.mdx)("p",null,"Without a package override, the resulting package is ",(0,l.mdx)("inlineCode",{parentName:"p"},"config_group.server.db"),".",(0,l.mdx)("br",{parentName:"p"}),"\n","With the ",(0,l.mdx)("strong",{parentName:"p"},"@","_","here","_")," keyword, The resulting package is the same as the containing config (",(0,l.mdx)("inlineCode",{parentName:"p"},"config_group"),"). "),(0,l.mdx)("h5",{id:"absolute-keywords"},"Absolute keywords:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("strong",{parentName:"li"},"@","_","group","_"),": ","_","group","_"," is the absolute default package of the config (",(0,l.mdx)("inlineCode",{parentName:"li"},"server.db"),")"),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("strong",{parentName:"li"},"@","_","global","_"),": The global package. Anything following ","_","global","_"," is absolute.",(0,l.mdx)("br",{parentName:"li"}),"e.g. ",(0,l.mdx)("strong",{parentName:"li"},"@","_","global","_",".foo")," becomes ",(0,l.mdx)("inlineCode",{parentName:"li"},"foo"),".")),(0,l.mdx)("h3",{id:"overriding-the-package-via-the-package-directive"},"Overriding the package via the package directive"),(0,l.mdx)("p",null,"The @package directive changes the package of a config file. The package specified by a @package directive is always absolute."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/db/mysql.yaml" {1}',title:'"server/db/mysql.yaml"',"{1}":!0},"# @package foo.bar\nname: mysql\n")),(0,l.mdx)("p",null,"To change the package to the global (empty) package, use the keyword ",(0,l.mdx)("inlineCode",{parentName:"p"},"_global_"),"."),(0,l.mdx)("h3",{id:"using-a-config-group-more-than-once"},"Using a config group more than once"),(0,l.mdx)("p",null,"The following example adds the ",(0,l.mdx)("inlineCode",{parentName:"p"},"server/db/mysql")," config in the packages ",(0,l.mdx)("inlineCode",{parentName:"p"},"src")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"dst"),"."),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - server/db@src: mysql\n - server/db@dst: mysql\n\n"))),(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py"',title:'"$',python:!0,'my_app.py"':!0},"src:\n name: mysql\ndst:\n name: mysql\n")))),(0,l.mdx)("p",null,"When overriding config groups with a non-default package, the package must be used:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py server/db@src=sqlite"',title:'"$',python:!0,"my_app.py":!0,"server/db@src":'sqlite"'},"src:\n name: sqlite\ndst:\n name: mysql\n")))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/141a01e8.cd0b22fc.js b/assets/js/141a01e8.cd0b22fc.js new file mode 100644 index 0000000000..ef66ff1146 --- /dev/null +++ b/assets/js/141a01e8.cd0b22fc.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[20],{15680:(e,a,n)=>{n.r(a),n.d(a,{MDXContext:()=>m,MDXProvider:()=>p,mdx:()=>f,useMDXComponents:()=>c,withMDXComponents:()=>d});var t=n(96540);function r(e,a,n){return a in e?Object.defineProperty(e,a,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[a]=n,e}function l(){return l=Object.assign||function(e){for(var a=1;a=0||(r[n]=e[n]);return r}(e,a);if(Object.getOwnPropertySymbols){var l=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var m=t.createContext({}),d=function(e){return function(a){var n=c(a.components);return t.createElement(e,l({},a,{components:n}))}},c=function(e){var a=t.useContext(m),n=a;return e&&(n="function"==typeof e?e(a):o(o({},a),e)),n},p=function(e){var a=c(e.components);return t.createElement(m.Provider,{value:a},e.children)},g={inlineCode:"code",wrapper:function(e){var a=e.children;return t.createElement(t.Fragment,{},a)}},u=t.forwardRef((function(e,a){var n=e.components,r=e.mdxType,l=e.originalType,i=e.parentName,m=s(e,["components","mdxType","originalType","parentName"]),d=c(n),p=r,u=d["".concat(i,".").concat(p)]||d[p]||g[p]||l;return n?t.createElement(u,o(o({ref:a},m),{},{components:n})):t.createElement(u,o({ref:a},m))}));function f(e,a){var n=arguments,r=a&&a.mdxType;if("string"==typeof e||r){var l=n.length,i=new Array(l);i[0]=u;var o={};for(var s in a)hasOwnProperty.call(a,s)&&(o[s]=a[s]);o.originalType=e,o.mdxType="string"==typeof e?e:r,i[1]=o;for(var m=2;m{n.r(a),n.d(a,{contentTitle:()=>s,default:()=>p,frontMatter:()=>o,metadata:()=>m,toc:()=>d});var t=n(58168),r=n(98587),l=(n(96540),n(15680)),i=["components"],o={id:"overriding_packages",title:"Packages"},s=void 0,m={unversionedId:"advanced/overriding_packages",id:"version-1.1/advanced/overriding_packages",title:"Packages",description:"The package determines where the content of each input config is placed in the output config.",source:"@site/versioned_docs/version-1.1/advanced/overriding_packages.md",sourceDirName:"advanced",slug:"/advanced/overriding_packages",permalink:"/docs/1.1/advanced/overriding_packages",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/advanced/overriding_packages.md",tags:[],version:"1.1",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"overriding_packages",title:"Packages"},sidebar:"version-1.1/docs",previous:{title:"The Defaults List",permalink:"/docs/1.1/advanced/defaults_list"},next:{title:"Overview",permalink:"/docs/1.1/advanced/instantiate_objects/overview"}},d=[{value:"An example using only default packages",id:"an-example-using-only-default-packages",children:[],level:3},{value:"Overriding packages using the Defaults List",id:"overriding-packages-using-the-defaults-list",children:[{value:"Default List package keywords",id:"default-list-package-keywords",children:[{value:"Absolute keywords:",id:"absolute-keywords",children:[],level:5}],level:4}],level:3},{value:"Overriding the package via the package directive",id:"overriding-the-package-via-the-package-directive",children:[],level:3},{value:"Using a config group more than once",id:"using-a-config-group-more-than-once",children:[],level:3}],c={toc:d};function p(e){var a=e.components,n=(0,r.A)(e,i);return(0,l.mdx)("wrapper",(0,t.A)({},c,n,{components:a,mdxType:"MDXLayout"}),(0,l.mdx)("p",null,"The package determines where the content of each input config is placed in the output config.\nThe default package of an input config is derived from its Config Group. e.g. The default package of ",(0,l.mdx)("inlineCode",{parentName:"p"},"server/db/mysql.yaml")," is ",(0,l.mdx)("inlineCode",{parentName:"p"},"server.db"),"."),(0,l.mdx)("p",null,"The default package can be overridden ",(0,l.mdx)("a",{parentName:"p",href:"#overriding-packages-using-the-defaults-list"},"in the Defaults List"),"\nor via a ",(0,l.mdx)("a",{parentName:"p",href:"#overriding-the-package-via-the-package-directive"},"Package Directive")," at the top of the config file.\nChanging the package of a config can be useful when using a config from another library, or when using the same\nconfig group twice in the same app."),(0,l.mdx)("p",null,"The priority for determining the final package for a config is as follows:"),(0,l.mdx)("ol",null,(0,l.mdx)("li",{parentName:"ol"},"The package specified in the Defaults List (relative to the package of the including config)"),(0,l.mdx)("li",{parentName:"ol"},"The package specified in the Package Directive (absolute)"),(0,l.mdx)("li",{parentName:"ol"},"The default package")),(0,l.mdx)("p",null,"We will use the following configs in the examples below:"),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--4"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - server/apache\n\ndebug: false\n\n\n\n"))),(0,l.mdx)("div",{className:"col col--4"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/apache.yaml"',title:'"server/apache.yaml"'},"defaults:\n - db: mysql\n\nname: apache\n\n\n\n"))),(0,l.mdx)("div",{className:"col col--4"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/db/mysql.yaml"',title:'"server/db/mysql.yaml"'},"name: mysql\n")),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/db/sqlite.yaml"',title:'"server/db/sqlite.yaml"'},"name: sqlite\n")))),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Config directory structure"',title:'"Config',directory:!0,'structure"':!0},"\u251c\u2500\u2500 server\n\u2502 \u251c\u2500\u2500 db\n\u2502 \u2502 \u251c\u2500\u2500 mysql.yaml\n\u2502 \u2502 \u2514\u2500\u2500 sqlite.yaml\n\u2502 \u2514\u2500\u2500 apache.yaml\n\u2514\u2500\u2500 config.yaml\n")),(0,l.mdx)("h3",{id:"an-example-using-only-default-packages"},"An example using only default packages"),(0,l.mdx)("p",null,"The default package of ",(0,l.mdx)("em",{parentName:"p"},"config.yaml")," is the global package, of ",(0,l.mdx)("em",{parentName:"p"},"server/apache.yaml")," is ",(0,l.mdx)("em",{parentName:"p"},"server")," and of ",(0,l.mdx)("em",{parentName:"p"},"server/db/mysql.yaml")," is ",(0,l.mdx)("em",{parentName:"p"},"server.db"),". "),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py" {1-2}',title:'"$',python:!0,'my_app.py"':!0,"{1-2}":!0},"server:\n db:\n name: mysql\n name: apache\ndebug: false\n")))),(0,l.mdx)("h3",{id:"overriding-packages-using-the-defaults-list"},"Overriding packages using the Defaults List"),(0,l.mdx)("p",null,"By default, packages specified in the Defaults List are relative to the package of containing config.\nAs a consequence, overriding a package relocates the entire subtree. "),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--4"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {2}',title:'"config.yaml"',"{2}":!0},"defaults:\n - server/apache@admin\n\ndebug: false\n\n"))),(0,l.mdx)("div",{className:"col col--4"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/apache.yaml" {2}',title:'"server/apache.yaml"',"{2}":!0},"defaults:\n - db@backup: mysql\n\nname: apache\n\n"))),(0,l.mdx)("div",{className:"col col--4"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Output config" {1-4}',title:'"Output','config"':!0,"{1-4}":!0},"admin:\n backup:\n name: mysql\n name: apache\ndebug: false\n")))),(0,l.mdx)("p",null,"Note that content of ",(0,l.mdx)("em",{parentName:"p"},"server/apache.yaml")," is relocated to ",(0,l.mdx)("em",{parentName:"p"},"admin"),"\nand the content of ",(0,l.mdx)("em",{parentName:"p"},"server/db/mysql.yaml")," to ",(0,l.mdx)("em",{parentName:"p"},"admin.backup"),"."),(0,l.mdx)("h4",{id:"default-list-package-keywords"},"Default List package keywords"),(0,l.mdx)("p",null,"We will use this example, replacing ",(0,l.mdx)("em",{parentName:"p"},"<@PACKAGE>")," to demonstrate different cases:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config_group/config.yaml"',title:'"config_group/config.yaml"'},"defaults:\n - /server/db<@PACKAGE>: mysql\n")),(0,l.mdx)("p",null,"Without a package override, the resulting package is ",(0,l.mdx)("inlineCode",{parentName:"p"},"config_group.server.db"),".",(0,l.mdx)("br",{parentName:"p"}),"\n","With the ",(0,l.mdx)("strong",{parentName:"p"},"@","_","here","_")," keyword, The resulting package is the same as the containing config (",(0,l.mdx)("inlineCode",{parentName:"p"},"config_group"),"). "),(0,l.mdx)("h5",{id:"absolute-keywords"},"Absolute keywords:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("strong",{parentName:"li"},"@","_","group","_"),": ","_","group","_"," is the absolute default package of the config (",(0,l.mdx)("inlineCode",{parentName:"li"},"server.db"),")"),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("strong",{parentName:"li"},"@","_","global","_"),": The global package. Anything following ","_","global","_"," is absolute.",(0,l.mdx)("br",{parentName:"li"}),"e.g. ",(0,l.mdx)("strong",{parentName:"li"},"@","_","global","_",".foo")," becomes ",(0,l.mdx)("inlineCode",{parentName:"li"},"foo"),".")),(0,l.mdx)("h3",{id:"overriding-the-package-via-the-package-directive"},"Overriding the package via the package directive"),(0,l.mdx)("p",null,"The @package directive changes the package of a config file. The package specified by a @package directive is always absolute."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/db/mysql.yaml" {1}',title:'"server/db/mysql.yaml"',"{1}":!0},"# @package foo.bar\nname: mysql\n")),(0,l.mdx)("p",null,"To change the package to the global (empty) package, use the keyword ",(0,l.mdx)("inlineCode",{parentName:"p"},"_global_"),"."),(0,l.mdx)("h3",{id:"using-a-config-group-more-than-once"},"Using a config group more than once"),(0,l.mdx)("p",null,"The following example adds the ",(0,l.mdx)("inlineCode",{parentName:"p"},"server/db/mysql")," config in the packages ",(0,l.mdx)("inlineCode",{parentName:"p"},"src")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"dst"),"."),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - server/db@src: mysql\n - server/db@dst: mysql\n\n"))),(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py"',title:'"$',python:!0,'my_app.py"':!0},"src:\n name: mysql\ndst:\n name: mysql\n")))),(0,l.mdx)("p",null,"When overriding config groups with a non-default package, the package must be used:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py server/db@src=sqlite"',title:'"$',python:!0,"my_app.py":!0,"server/db@src":'sqlite"'},"src:\n name: sqlite\ndst:\n name: mysql\n")))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1434836b.106f7fdd.js b/assets/js/1434836b.106f7fdd.js new file mode 100644 index 0000000000..d3cd8675d9 --- /dev/null +++ b/assets/js/1434836b.106f7fdd.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[494],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>c,MDXProvider:()=>s,mdx:()=>f,useMDXComponents:()=>m,withMDXComponents:()=>p});var a=t(96540);function r(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(r[t]=e[t]);return r}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(r[t]=e[t])}return r}var c=a.createContext({}),p=function(e){return function(n){var t=m(n.components);return a.createElement(e,i({},n,{components:t}))}},m=function(e){var n=a.useContext(c),t=n;return e&&(t="function"==typeof e?e(n):o(o({},n),e)),t},s=function(e){var n=m(e.components);return a.createElement(c.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},g=a.forwardRef((function(e,n){var t=e.components,r=e.mdxType,i=e.originalType,d=e.parentName,c=l(e,["components","mdxType","originalType","parentName"]),p=m(t),s=r,g=p["".concat(d,".").concat(s)]||p[s]||u[s]||i;return t?a.createElement(g,o(o({ref:n},c),{},{components:t})):a.createElement(g,o({ref:n},c))}));function f(e,n){var t=arguments,r=n&&n.mdxType;if("string"==typeof e||r){var i=t.length,d=new Array(i);d[0]=g;var o={};for(var l in n)hasOwnProperty.call(n,l)&&(o[l]=n[l]);o.originalType=e,o.mdxType="string"==typeof e?e:r,d[1]=o;for(var c=2;c{t.r(n),t.d(n,{contentTitle:()=>l,default:()=>s,frontMatter:()=>o,metadata:()=>c,toc:()=>p});var a=t(58168),r=t(98587),i=(t(96540),t(15680)),d=["components"],o={id:"adding_a_package_directive",title:"Adding an @package directive",hide_title:!0},l=void 0,c={unversionedId:"upgrades/0.11_to_1.0/adding_a_package_directive",id:"upgrades/0.11_to_1.0/adding_a_package_directive",title:"Adding an @package directive",description:"Adding an @package directive",source:"@site/docs/upgrades/0.11_to_1.0/adding_a_package_directive.md",sourceDirName:"upgrades/0.11_to_1.0",slug:"/upgrades/0.11_to_1.0/adding_a_package_directive",permalink:"/docs/upgrades/0.11_to_1.0/adding_a_package_directive",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/upgrades/0.11_to_1.0/adding_a_package_directive.md",tags:[],version:"current",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"adding_a_package_directive",title:"Adding an @package directive",hide_title:!0},sidebar:"docs",previous:{title:"Config path changes",permalink:"/docs/upgrades/0.11_to_1.0/config_path_changes"},next:{title:"strict flag mode deprecation",permalink:"/docs/upgrades/0.11_to_1.0/strict_mode_flag_deprecated"}},p=[{value:"Adding an @package directive",id:"adding-an-package-directive",children:[],level:2},{value:"Upgrade instructions:",id:"upgrade-instructions",children:[{value:"Recommended (~10 seconds per config file):",id:"recommended-10-seconds-per-config-file",children:[],level:3},{value:"Alternative (not recommended):",id:"alternative-not-recommended",children:[],level:3},{value:"Example for case 1:",id:"example-for-case-1",children:[{value:"Before",id:"before",children:[],level:4},{value:"After",id:"after",children:[],level:4}],level:3},{value:"Example for case 2:",id:"example-for-case-2",children:[],level:3}],level:2}],m={toc:p};function s(e){var n=e.components,t=(0,r.A)(e,d);return(0,i.mdx)("wrapper",(0,a.A)({},m,t,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)("h2",{id:"adding-an-package-directive"},"Adding an @package directive"),(0,i.mdx)("p",null,"Hydra 1.0 introduces the concept of a config ",(0,i.mdx)("inlineCode",{parentName:"p"},"package"),". A ",(0,i.mdx)("inlineCode",{parentName:"p"},"package")," is the common parent\npath of all nodes in the config file."),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"In Hydra 0.11, there was an implicit default of ",(0,i.mdx)("inlineCode",{parentName:"li"},"_global_"),' ("")'),(0,i.mdx)("li",{parentName:"ul"},"In Hydra 1.1 the default will be ",(0,i.mdx)("inlineCode",{parentName:"li"},"_group_")," (the name of the config group)."),(0,i.mdx)("li",{parentName:"ul"},"Hydra 1.0 maintains the implicit default of ",(0,i.mdx)("inlineCode",{parentName:"li"},"_global_")," and issues a warning for\nany config group file without a ",(0,i.mdx)("inlineCode",{parentName:"li"},"@package")," directive.")),(0,i.mdx)("p",null,"By adding an explicit ",(0,i.mdx)("inlineCode",{parentName:"p"},"@package")," to these configs now, you guarantee that your configs\nwill not break when you upgrade to Hydra 1.1."),(0,i.mdx)("p",null,"The ",(0,i.mdx)("inlineCode",{parentName:"p"},"@package")," directive is described in details ",(0,i.mdx)("a",{parentName:"p",href:"/docs/advanced/overriding_packages"},"here"),". "),(0,i.mdx)("h2",{id:"upgrade-instructions"},"Upgrade instructions:"),(0,i.mdx)("h3",{id:"recommended-10-seconds-per-config-file"},"Recommended (~10 seconds per config file):"),(0,i.mdx)("p",null,(0,i.mdx)("inlineCode",{parentName:"p"},"Case 1"),": For config files where the common parent path matches the config group name: "),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"Add ",(0,i.mdx)("inlineCode",{parentName:"li"},"# @package _group_")," to the top of every config group file"),(0,i.mdx)("li",{parentName:"ul"},"Remove the common parent path config file like in the example below.")),(0,i.mdx)("p",null,(0,i.mdx)("inlineCode",{parentName:"p"},"Case 2"),": For files without a common parent path:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"Add ",(0,i.mdx)("inlineCode",{parentName:"li"},"# @package _global_"),".")),(0,i.mdx)("h3",{id:"alternative-not-recommended"},"Alternative (not recommended):"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"If you do not want to restructure the config at this time use ",(0,i.mdx)("inlineCode",{parentName:"li"},"Case 2")," for all your config files.")),(0,i.mdx)("h3",{id:"example-for-case-1"},"Example for ",(0,i.mdx)("inlineCode",{parentName:"h3"},"case 1"),":"),(0,i.mdx)("h4",{id:"before"},"Before"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml"',title:'"db/mysql.yaml"'},"db:\n driver: mysql\n host: localhost\n port: 3306\n")),(0,i.mdx)("h4",{id:"after"},"After"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml"',title:'"db/mysql.yaml"'},"# @package _group_\ndriver: mysql\nhost: localhost\nport: 3306\n")),(0,i.mdx)("p",null,"The interpretations of the before and after files are identical."),(0,i.mdx)("h3",{id:"example-for-case-2"},"Example for ",(0,i.mdx)("inlineCode",{parentName:"h3"},"case 2"),":"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="env/prod.yaml"',title:'"env/prod.yaml"'},"# @package _global_\ndb:\n driver: mysql\n host: 10.0.0.11\n port: 3306\n\nwebserver:\n host: 10.0.0.11\n port: 443\n")))}s.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1434836b.f27037c0.js b/assets/js/1434836b.f27037c0.js deleted file mode 100644 index 54b3a14a57..0000000000 --- a/assets/js/1434836b.f27037c0.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[494],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>c,MDXProvider:()=>s,mdx:()=>f,useMDXComponents:()=>m,withMDXComponents:()=>p});var a=t(96540);function r(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(r[t]=e[t]);return r}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(r[t]=e[t])}return r}var c=a.createContext({}),p=function(e){return function(n){var t=m(n.components);return a.createElement(e,i({},n,{components:t}))}},m=function(e){var n=a.useContext(c),t=n;return e&&(t="function"==typeof e?e(n):o(o({},n),e)),t},s=function(e){var n=m(e.components);return a.createElement(c.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},g=a.forwardRef((function(e,n){var t=e.components,r=e.mdxType,i=e.originalType,d=e.parentName,c=l(e,["components","mdxType","originalType","parentName"]),p=m(t),s=r,g=p["".concat(d,".").concat(s)]||p[s]||u[s]||i;return t?a.createElement(g,o(o({ref:n},c),{},{components:t})):a.createElement(g,o({ref:n},c))}));function f(e,n){var t=arguments,r=n&&n.mdxType;if("string"==typeof e||r){var i=t.length,d=new Array(i);d[0]=g;var o={};for(var l in n)hasOwnProperty.call(n,l)&&(o[l]=n[l]);o.originalType=e,o.mdxType="string"==typeof e?e:r,d[1]=o;for(var c=2;c{t.r(n),t.d(n,{contentTitle:()=>l,default:()=>s,frontMatter:()=>o,metadata:()=>c,toc:()=>p});var a=t(58168),r=t(98587),i=(t(96540),t(15680)),d=["components"],o={id:"adding_a_package_directive",title:"Adding an @package directive",hide_title:!0},l=void 0,c={unversionedId:"upgrades/0.11_to_1.0/adding_a_package_directive",id:"upgrades/0.11_to_1.0/adding_a_package_directive",title:"Adding an @package directive",description:"Adding an @package directive",source:"@site/docs/upgrades/0.11_to_1.0/adding_a_package_directive.md",sourceDirName:"upgrades/0.11_to_1.0",slug:"/upgrades/0.11_to_1.0/adding_a_package_directive",permalink:"/docs/upgrades/0.11_to_1.0/adding_a_package_directive",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/upgrades/0.11_to_1.0/adding_a_package_directive.md",tags:[],version:"current",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"adding_a_package_directive",title:"Adding an @package directive",hide_title:!0},sidebar:"docs",previous:{title:"Config path changes",permalink:"/docs/upgrades/0.11_to_1.0/config_path_changes"},next:{title:"strict flag mode deprecation",permalink:"/docs/upgrades/0.11_to_1.0/strict_mode_flag_deprecated"}},p=[{value:"Adding an @package directive",id:"adding-an-package-directive",children:[],level:2},{value:"Upgrade instructions:",id:"upgrade-instructions",children:[{value:"Recommended (~10 seconds per config file):",id:"recommended-10-seconds-per-config-file",children:[],level:3},{value:"Alternative (not recommended):",id:"alternative-not-recommended",children:[],level:3},{value:"Example for case 1:",id:"example-for-case-1",children:[{value:"Before",id:"before",children:[],level:4},{value:"After",id:"after",children:[],level:4}],level:3},{value:"Example for case 2:",id:"example-for-case-2",children:[],level:3}],level:2}],m={toc:p};function s(e){var n=e.components,t=(0,r.A)(e,d);return(0,i.mdx)("wrapper",(0,a.A)({},m,t,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)("h2",{id:"adding-an-package-directive"},"Adding an @package directive"),(0,i.mdx)("p",null,"Hydra 1.0 introduces the concept of a config ",(0,i.mdx)("inlineCode",{parentName:"p"},"package"),". A ",(0,i.mdx)("inlineCode",{parentName:"p"},"package")," is the common parent\npath of all nodes in the config file."),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"In Hydra 0.11, there was an implicit default of ",(0,i.mdx)("inlineCode",{parentName:"li"},"_global_"),' ("")'),(0,i.mdx)("li",{parentName:"ul"},"In Hydra 1.1 the default will be ",(0,i.mdx)("inlineCode",{parentName:"li"},"_group_")," (the name of the config group)."),(0,i.mdx)("li",{parentName:"ul"},"Hydra 1.0 maintains the implicit default of ",(0,i.mdx)("inlineCode",{parentName:"li"},"_global_")," and issues a warning for\nany config group file without a ",(0,i.mdx)("inlineCode",{parentName:"li"},"@package")," directive.")),(0,i.mdx)("p",null,"By adding an explicit ",(0,i.mdx)("inlineCode",{parentName:"p"},"@package")," to these configs now, you guarantee that your configs\nwill not break when you upgrade to Hydra 1.1."),(0,i.mdx)("p",null,"The ",(0,i.mdx)("inlineCode",{parentName:"p"},"@package")," directive is described in details ",(0,i.mdx)("a",{parentName:"p",href:"/docs/advanced/overriding_packages"},"here"),". "),(0,i.mdx)("h2",{id:"upgrade-instructions"},"Upgrade instructions:"),(0,i.mdx)("h3",{id:"recommended-10-seconds-per-config-file"},"Recommended (~10 seconds per config file):"),(0,i.mdx)("p",null,(0,i.mdx)("inlineCode",{parentName:"p"},"Case 1"),": For config files where the common parent path matches the config group name: "),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"Add ",(0,i.mdx)("inlineCode",{parentName:"li"},"# @package _group_")," to the top of every config group file"),(0,i.mdx)("li",{parentName:"ul"},"Remove the common parent path config file like in the example below.")),(0,i.mdx)("p",null,(0,i.mdx)("inlineCode",{parentName:"p"},"Case 2"),": For files without a common parent path:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"Add ",(0,i.mdx)("inlineCode",{parentName:"li"},"# @package _global_"),".")),(0,i.mdx)("h3",{id:"alternative-not-recommended"},"Alternative (not recommended):"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"If you do not want to restructure the config at this time use ",(0,i.mdx)("inlineCode",{parentName:"li"},"Case 2")," for all your config files.")),(0,i.mdx)("h3",{id:"example-for-case-1"},"Example for ",(0,i.mdx)("inlineCode",{parentName:"h3"},"case 1"),":"),(0,i.mdx)("h4",{id:"before"},"Before"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml"',title:'"db/mysql.yaml"'},"db:\n driver: mysql\n host: localhost\n port: 3306\n")),(0,i.mdx)("h4",{id:"after"},"After"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml"',title:'"db/mysql.yaml"'},"# @package _group_\ndriver: mysql\nhost: localhost\nport: 3306\n")),(0,i.mdx)("p",null,"The interpretations of the before and after files are identical."),(0,i.mdx)("h3",{id:"example-for-case-2"},"Example for ",(0,i.mdx)("inlineCode",{parentName:"h3"},"case 2"),":"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="env/prod.yaml"',title:'"env/prod.yaml"'},"# @package _global_\ndb:\n driver: mysql\n host: 10.0.0.11\n port: 3306\n\nwebserver:\n host: 10.0.0.11\n port: 443\n")))}s.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1443f4ed.3b5a3f68.js b/assets/js/1443f4ed.3b5a3f68.js deleted file mode 100644 index 2b6c015ac9..0000000000 --- a/assets/js/1443f4ed.3b5a3f68.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[2082],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>m,MDXProvider:()=>u,mdx:()=>f,useMDXComponents:()=>d,withMDXComponents:()=>s});var a=t(96540);function i(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function r(){return r=Object.assign||function(e){for(var n=1;n=0||(i[t]=e[t]);return i}(e,n);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(i[t]=e[t])}return i}var m=a.createContext({}),s=function(e){return function(n){var t=d(n.components);return a.createElement(e,r({},n,{components:t}))}},d=function(e){var n=a.useContext(m),t=n;return e&&(t="function"==typeof e?e(n):o(o({},n),e)),t},u=function(e){var n=d(e.components);return a.createElement(m.Provider,{value:n},e.children)},p={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},g=a.forwardRef((function(e,n){var t=e.components,i=e.mdxType,r=e.originalType,l=e.parentName,m=c(e,["components","mdxType","originalType","parentName"]),s=d(t),u=i,g=s["".concat(l,".").concat(u)]||s[u]||p[u]||r;return t?a.createElement(g,o(o({ref:n},m),{},{components:t})):a.createElement(g,o({ref:n},m))}));function f(e,n){var t=arguments,i=n&&n.mdxType;if("string"==typeof e||i){var r=t.length,l=new Array(r);l[0]=g;var o={};for(var c in n)hasOwnProperty.call(n,c)&&(o[c]=n[c]);o.originalType=e,o.mdxType="string"==typeof e?e:i,l[1]=o;for(var m=2;m{t.d(n,{A:()=>c,C:()=>m});var a=t(58168),i=t(96540),r=t(75489),l=t(44586),o=t(74098);function c(e){return i.createElement(r.default,(0,a.A)({},e,{to:(n=e.to,c=(0,o.useActiveVersion)(),(0,l.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==c?void 0:c.name)?t:"current"]+n),target:"_blank"}));var n,t,c}function m(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return i.createElement(c,e,i.createElement("span",null,"\xa0"),i.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},18756:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>c,default:()=>u,frontMatter:()=>o,metadata:()=>m,toc:()=>s});var a=t(58168),i=t(98587),r=(t(96540),t(15680)),l=(t(49595),["components"]),o={id:"configuring_plugins",title:"Configuring Plugins"},c=void 0,m={unversionedId:"patterns/configuring_plugins",id:"version-1.3/patterns/configuring_plugins",title:"Configuring Plugins",description:"Hydra plugins usually come with sensible defaults which work with minimal configuration.",source:"@site/versioned_docs/version-1.3/patterns/configuring_plugins.md",sourceDirName:"patterns",slug:"/patterns/configuring_plugins",permalink:"/docs/1.3/patterns/configuring_plugins",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/patterns/configuring_plugins.md",tags:[],version:"1.3",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"configuring_plugins",title:"Configuring Plugins"},sidebar:"docs",previous:{title:"Configuring Experiments",permalink:"/docs/1.3/patterns/configuring_experiments"},next:{title:"Selecting multiple configs from a Config Group",permalink:"/docs/1.3/patterns/select_multiple_configs_from_config_group"}},s=[{value:"Overriding in primary config",id:"overriding-in-primary-config",children:[],level:3},{value:"Extending plugin default config",id:"extending-plugin-default-config",children:[],level:3}],d={toc:s};function u(e){var n=e.components,t=(0,i.A)(e,l);return(0,r.mdx)("wrapper",(0,a.A)({},d,t,{components:n,mdxType:"MDXLayout"}),(0,r.mdx)("p",null,"Hydra plugins usually come with sensible defaults which work with minimal configuration.\nThere are two primary ways to customize the configuration of a plugin:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Overriding it directly in your primary config"),(0,r.mdx)("li",{parentName:"ul"},"Extending the config and using it from your primary config.")),(0,r.mdx)("p",null,"The first method is the simpler, but it makes it harder to switch to a different plugin configuration.\nThe second method is a bit more complicated, but makes it easier to switch between different plugin configurations."),(0,r.mdx)("p",null,"The following methods apply to all Hydra plugins. In the following examples, we will configure an imaginary Launcher plugin\n",(0,r.mdx)("inlineCode",{parentName:"p"},"MoonLauncher"),". The Launcher has two modes: ",(0,r.mdx)("inlineCode",{parentName:"p"},"falcon9"),", which actually launches the application to the Moon and\n",(0,r.mdx)("inlineCode",{parentName:"p"},"sim")," which simulates a launch."),(0,r.mdx)("p",null,"The config schema for MoonLauncher looks like:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},"@dataclass\nclass Falcon9Conf:\n ton_fuel: int = 10\n\n\n\n\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},"@dataclass\nclass Simulation:\n ton_fuel: int = 10\n window_size:\n width: 1024\n height: 768\n\n")))),(0,r.mdx)("h3",{id:"overriding-in-primary-config"},"Overriding in primary config"),(0,r.mdx)("p",null,"We can directly override Launcher config in primary config."),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"a: 1\n\nhydra:\n launcher:\n ton_fuel: 2\n\n\n\n\n\n\n\n\n\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-commandline",metastring:'title="command-line override"',title:'"command-line','override"':!0},"hydra/launcher=falcon9\n\n\n")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="resulting launcher config" {3}',title:'"resulting',launcher:!0,'config"':!0,"":!0,"{3}":!0},"hydra:\n launcher:\n ton_fuel: 2\n\n\n\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-commandline",metastring:'title="command-line override"',title:'"command-line','override"':!0},"hydra/launcher=sim\n\n\n")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="resulting launcher config" {3}',title:'"resulting',launcher:!0,'config"':!0,"":!0,"{3}":!0},"hydra:\n launcher:\n ton_fuel: 2\n window_size:\n width: 1024\n height: 768\n")))),(0,r.mdx)("p",null,"This approach makes the assumption that the Launcher used has all the fields we are overriding.\nIf we wanted to override a field that exists in the Simulation Launcher but not in the Falcon9 Launcher,\nlike ",(0,r.mdx)("inlineCode",{parentName:"p"},"window_size.width"),", we would no longer be able to use the Falcon9 Launcher! The next section solves this problem."),(0,r.mdx)("h3",{id:"extending-plugin-default-config"},"Extending plugin default config"),(0,r.mdx)("p",null,"This section assumes that you are familiar with the contents of ",(0,r.mdx)("a",{parentName:"p",href:"/docs/1.3/patterns/extending_configs"},"Common Patterns/Extending Configs"),"."),(0,r.mdx)("p",null,"Extending plugin default config has several advantages:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Separate configuration concerns, keep primary config clean."),(0,r.mdx)("li",{parentName:"ul"},"Easier to switch between different plugin configurations."),(0,r.mdx)("li",{parentName:"ul"},"Provides flexibility when a Plugin has different modes\nthat requires different schema.")),(0,r.mdx)("p",null,"Say that we want to override certain values for different Launcher mode:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="hydra/launcher/my_falcon9.yaml" {4}',title:'"hydra/launcher/my_falcon9.yaml"',"{4}":!0},"defaults:\n - falcon9\n\nton_fuel: 2\n\n\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="hydra/sweeper/my_sim.yaml" {5}',title:'"hydra/sweeper/my_sim.yaml"',"{5}":!0},"defaults:\n - sim\n\nwindow_size:\n width: 768\n\n")))),(0,r.mdx)("p",null,"We can easily user command-line overrides to get the configuration needed:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-commandline",metastring:'title="command-line override"',title:'"command-line','override"':!0},"hydra/launcher=my_falcon9\n\n\n")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="resulting launcher config" {3}',title:'"resulting',launcher:!0,'config"':!0,"":!0,"{3}":!0},"hydra:\n launcher:\n ton_fuel: 2\n\n\n\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-commandline",metastring:'title="command-line override"',title:'"command-line','override"':!0},"hydra/launcher=my_sim\n\n\n")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="resulting launcher config" {5}',title:'"resulting',launcher:!0,'config"':!0,"":!0,"{5}":!0},"hydra:\n launcher:\n ton_fuel: 10\n window_size:\n width: 768\n height: 768\n")))))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1443f4ed.d36802b3.js b/assets/js/1443f4ed.d36802b3.js new file mode 100644 index 0000000000..49bfc7ed63 --- /dev/null +++ b/assets/js/1443f4ed.d36802b3.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[2082],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>m,MDXProvider:()=>u,mdx:()=>f,useMDXComponents:()=>d,withMDXComponents:()=>s});var a=t(96540);function i(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function r(){return r=Object.assign||function(e){for(var n=1;n=0||(i[t]=e[t]);return i}(e,n);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(i[t]=e[t])}return i}var m=a.createContext({}),s=function(e){return function(n){var t=d(n.components);return a.createElement(e,r({},n,{components:t}))}},d=function(e){var n=a.useContext(m),t=n;return e&&(t="function"==typeof e?e(n):o(o({},n),e)),t},u=function(e){var n=d(e.components);return a.createElement(m.Provider,{value:n},e.children)},p={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},g=a.forwardRef((function(e,n){var t=e.components,i=e.mdxType,r=e.originalType,l=e.parentName,m=c(e,["components","mdxType","originalType","parentName"]),s=d(t),u=i,g=s["".concat(l,".").concat(u)]||s[u]||p[u]||r;return t?a.createElement(g,o(o({ref:n},m),{},{components:t})):a.createElement(g,o({ref:n},m))}));function f(e,n){var t=arguments,i=n&&n.mdxType;if("string"==typeof e||i){var r=t.length,l=new Array(r);l[0]=g;var o={};for(var c in n)hasOwnProperty.call(n,c)&&(o[c]=n[c]);o.originalType=e,o.mdxType="string"==typeof e?e:i,l[1]=o;for(var m=2;m{t.d(n,{A:()=>c,C:()=>m});var a=t(58168),i=t(96540),r=t(75489),l=t(44586),o=t(74098);function c(e){return i.createElement(r.default,(0,a.A)({},e,{to:(n=e.to,c=(0,o.useActiveVersion)(),(0,l.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==c?void 0:c.name)?t:"current"]+n),target:"_blank"}));var n,t,c}function m(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return i.createElement(c,e,i.createElement("span",null,"\xa0"),i.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},18756:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>c,default:()=>u,frontMatter:()=>o,metadata:()=>m,toc:()=>s});var a=t(58168),i=t(98587),r=(t(96540),t(15680)),l=(t(49595),["components"]),o={id:"configuring_plugins",title:"Configuring Plugins"},c=void 0,m={unversionedId:"patterns/configuring_plugins",id:"version-1.3/patterns/configuring_plugins",title:"Configuring Plugins",description:"Hydra plugins usually come with sensible defaults which work with minimal configuration.",source:"@site/versioned_docs/version-1.3/patterns/configuring_plugins.md",sourceDirName:"patterns",slug:"/patterns/configuring_plugins",permalink:"/docs/1.3/patterns/configuring_plugins",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/patterns/configuring_plugins.md",tags:[],version:"1.3",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"configuring_plugins",title:"Configuring Plugins"},sidebar:"docs",previous:{title:"Configuring Experiments",permalink:"/docs/1.3/patterns/configuring_experiments"},next:{title:"Selecting multiple configs from a Config Group",permalink:"/docs/1.3/patterns/select_multiple_configs_from_config_group"}},s=[{value:"Overriding in primary config",id:"overriding-in-primary-config",children:[],level:3},{value:"Extending plugin default config",id:"extending-plugin-default-config",children:[],level:3}],d={toc:s};function u(e){var n=e.components,t=(0,i.A)(e,l);return(0,r.mdx)("wrapper",(0,a.A)({},d,t,{components:n,mdxType:"MDXLayout"}),(0,r.mdx)("p",null,"Hydra plugins usually come with sensible defaults which work with minimal configuration.\nThere are two primary ways to customize the configuration of a plugin:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Overriding it directly in your primary config"),(0,r.mdx)("li",{parentName:"ul"},"Extending the config and using it from your primary config.")),(0,r.mdx)("p",null,"The first method is the simpler, but it makes it harder to switch to a different plugin configuration.\nThe second method is a bit more complicated, but makes it easier to switch between different plugin configurations."),(0,r.mdx)("p",null,"The following methods apply to all Hydra plugins. In the following examples, we will configure an imaginary Launcher plugin\n",(0,r.mdx)("inlineCode",{parentName:"p"},"MoonLauncher"),". The Launcher has two modes: ",(0,r.mdx)("inlineCode",{parentName:"p"},"falcon9"),", which actually launches the application to the Moon and\n",(0,r.mdx)("inlineCode",{parentName:"p"},"sim")," which simulates a launch."),(0,r.mdx)("p",null,"The config schema for MoonLauncher looks like:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},"@dataclass\nclass Falcon9Conf:\n ton_fuel: int = 10\n\n\n\n\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},"@dataclass\nclass Simulation:\n ton_fuel: int = 10\n window_size:\n width: 1024\n height: 768\n\n")))),(0,r.mdx)("h3",{id:"overriding-in-primary-config"},"Overriding in primary config"),(0,r.mdx)("p",null,"We can directly override Launcher config in primary config."),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"a: 1\n\nhydra:\n launcher:\n ton_fuel: 2\n\n\n\n\n\n\n\n\n\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-commandline",metastring:'title="command-line override"',title:'"command-line','override"':!0},"hydra/launcher=falcon9\n\n\n")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="resulting launcher config" {3}',title:'"resulting',launcher:!0,'config"':!0,"":!0,"{3}":!0},"hydra:\n launcher:\n ton_fuel: 2\n\n\n\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-commandline",metastring:'title="command-line override"',title:'"command-line','override"':!0},"hydra/launcher=sim\n\n\n")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="resulting launcher config" {3}',title:'"resulting',launcher:!0,'config"':!0,"":!0,"{3}":!0},"hydra:\n launcher:\n ton_fuel: 2\n window_size:\n width: 1024\n height: 768\n")))),(0,r.mdx)("p",null,"This approach makes the assumption that the Launcher used has all the fields we are overriding.\nIf we wanted to override a field that exists in the Simulation Launcher but not in the Falcon9 Launcher,\nlike ",(0,r.mdx)("inlineCode",{parentName:"p"},"window_size.width"),", we would no longer be able to use the Falcon9 Launcher! The next section solves this problem."),(0,r.mdx)("h3",{id:"extending-plugin-default-config"},"Extending plugin default config"),(0,r.mdx)("p",null,"This section assumes that you are familiar with the contents of ",(0,r.mdx)("a",{parentName:"p",href:"/docs/1.3/patterns/extending_configs"},"Common Patterns/Extending Configs"),"."),(0,r.mdx)("p",null,"Extending plugin default config has several advantages:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Separate configuration concerns, keep primary config clean."),(0,r.mdx)("li",{parentName:"ul"},"Easier to switch between different plugin configurations."),(0,r.mdx)("li",{parentName:"ul"},"Provides flexibility when a Plugin has different modes\nthat requires different schema.")),(0,r.mdx)("p",null,"Say that we want to override certain values for different Launcher mode:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="hydra/launcher/my_falcon9.yaml" {4}',title:'"hydra/launcher/my_falcon9.yaml"',"{4}":!0},"defaults:\n - falcon9\n\nton_fuel: 2\n\n\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="hydra/sweeper/my_sim.yaml" {5}',title:'"hydra/sweeper/my_sim.yaml"',"{5}":!0},"defaults:\n - sim\n\nwindow_size:\n width: 768\n\n")))),(0,r.mdx)("p",null,"We can easily user command-line overrides to get the configuration needed:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-commandline",metastring:'title="command-line override"',title:'"command-line','override"':!0},"hydra/launcher=my_falcon9\n\n\n")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="resulting launcher config" {3}',title:'"resulting',launcher:!0,'config"':!0,"":!0,"{3}":!0},"hydra:\n launcher:\n ton_fuel: 2\n\n\n\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-commandline",metastring:'title="command-line override"',title:'"command-line','override"':!0},"hydra/launcher=my_sim\n\n\n")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="resulting launcher config" {5}',title:'"resulting',launcher:!0,'config"':!0,"":!0,"{5}":!0},"hydra:\n launcher:\n ton_fuel: 10\n window_size:\n width: 768\n height: 768\n")))))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1483e3dc.be5f94fe.js b/assets/js/1483e3dc.be5f94fe.js new file mode 100644 index 0000000000..b9c76c4375 --- /dev/null +++ b/assets/js/1483e3dc.be5f94fe.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[7648],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>m,MDXProvider:()=>p,mdx:()=>f,useMDXComponents:()=>c,withMDXComponents:()=>d});var a=t(96540);function i(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function o(){return o=Object.assign||function(e){for(var n=1;n=0||(i[t]=e[t]);return i}(e,n);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(i[t]=e[t])}return i}var m=a.createContext({}),d=function(e){return function(n){var t=c(n.components);return a.createElement(e,o({},n,{components:t}))}},c=function(e){var n=a.useContext(m),t=n;return e&&(t="function"==typeof e?e(n):l(l({},n),e)),t},p=function(e){var n=c(e.components);return a.createElement(m.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},h=a.forwardRef((function(e,n){var t=e.components,i=e.mdxType,o=e.originalType,r=e.parentName,m=s(e,["components","mdxType","originalType","parentName"]),d=c(t),p=i,h=d["".concat(r,".").concat(p)]||d[p]||u[p]||o;return t?a.createElement(h,l(l({ref:n},m),{},{components:t})):a.createElement(h,l({ref:n},m))}));function f(e,n){var t=arguments,i=n&&n.mdxType;if("string"==typeof e||i){var o=t.length,r=new Array(o);r[0]=h;var l={};for(var s in n)hasOwnProperty.call(n,s)&&(l[s]=n[s]);l.originalType=e,l.mdxType="string"==typeof e?e:i,r[1]=l;for(var m=2;m{t.d(n,{A:()=>s,C:()=>m});var a=t(58168),i=t(96540),o=t(75489),r=t(44586),l=t(74098);function s(e){return i.createElement(o.default,(0,a.A)({},e,{to:(n=e.to,s=(0,l.useActiveVersion)(),(0,r.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==s?void 0:s.name)?t:"current"]+n),target:"_blank"}));var n,t,s}function m(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return i.createElement(s,e,i.createElement("span",null,"\xa0"),i.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},80487:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>m,default:()=>u,frontMatter:()=>s,metadata:()=>d,toc:()=>c});var a=t(58168),i=t(98587),o=(t(96540),t(15680)),r=t(49595),l=["components"],s={id:"compose_api",title:"Compose API",sidebar_label:"Compose API"},m=void 0,d={unversionedId:"advanced/compose_api",id:"version-1.2/advanced/compose_api",title:"Compose API",description:"The compose API can compose a config similarly to @hydra.main() anywhere in the code.",source:"@site/versioned_docs/version-1.2/advanced/compose_api.md",sourceDirName:"advanced",slug:"/advanced/compose_api",permalink:"/docs/1.2/advanced/compose_api",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/advanced/compose_api.md",tags:[],version:"1.2",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"compose_api",title:"Compose API",sidebar_label:"Compose API"},sidebar:"docs",previous:{title:"Structured Configs example",permalink:"/docs/1.2/advanced/instantiate_objects/structured_config"},next:{title:"Config Search Path",permalink:"/docs/1.2/advanced/search_path"}},c=[{value:"When to use the Compose API",id:"when-to-use-the-compose-api",children:[],level:3},{value:"Initialization methods",id:"initialization-methods",children:[],level:3},{value:"Code example",id:"code-example",children:[],level:3},{value:"API Documentation",id:"api-documentation",children:[],level:3}],p={toc:c};function u(e){var n=e.components,t=(0,i.A)(e,l);return(0,o.mdx)("wrapper",(0,a.A)({},p,t,{components:n,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"The compose API can compose a config similarly to ",(0,o.mdx)("inlineCode",{parentName:"p"},"@hydra.main()")," anywhere in the code.",(0,o.mdx)("br",{parentName:"p"}),"\n","Prior to calling compose(), you have to initialize Hydra: This can be done by using the standard ",(0,o.mdx)("inlineCode",{parentName:"p"},"@hydra.main()"),"\nor by calling one of the initialization methods listed below."),(0,o.mdx)("h3",{id:"when-to-use-the-compose-api"},"When to use the Compose API"),(0,o.mdx)("p",null,"The Compose API is useful when ",(0,o.mdx)("inlineCode",{parentName:"p"},"@hydra.main()")," is not applicable.\nFor example:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"Inside a Jupyter notebook (",(0,o.mdx)("a",{parentName:"li",href:"/docs/1.2/advanced/jupyter_notebooks"},"Example"),")"),(0,o.mdx)("li",{parentName:"ul"},"Inside a unit test (",(0,o.mdx)("a",{parentName:"li",href:"/docs/1.2/advanced/unit_testing"},"Example"),")"),(0,o.mdx)("li",{parentName:"ul"},"In parts of your application that does not have access to the command line (",(0,o.mdx)(r.A,{to:"examples/advanced/ad_hoc_composition",mdxType:"GithubLink"},"Example"),")."),(0,o.mdx)("li",{parentName:"ul"},"To compose multiple configuration objects (",(0,o.mdx)(r.A,{to:"examples/advanced/ray_example/ray_compose_example.py",mdxType:"GithubLink"},"Example with Ray"),").")),(0,o.mdx)("div",{class:"alert alert--info",role:"alert"},"Please avoid using the Compose API in cases where ",(0,o.mdx)("b",null,"@hydra.main()")," can be used. Doing so forfeits many of the benefits of Hydra (e.g., Tab completion, Multirun, Working directory management, Logging management and more)"),(0,o.mdx)("h3",{id:"initialization-methods"},"Initialization methods"),(0,o.mdx)("p",null,"There are 3 initialization methods:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"initialize()"),": Initialize with a config path relative to the caller"),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"initialize_config_module()")," : Initialize with config_module (absolute)"),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"initialize_config_dir()")," : Initialize with a config_dir on the file system (absolute)")),(0,o.mdx)("p",null,"All 3 can be used as methods or contexts.\nWhen used as methods, they are initializing Hydra globally and should only be called once.\nWhen used as contexts, they are initializing Hydra within the context can be used multiple times.\nLike ",(0,o.mdx)("b",null,"@hydra.main()")," all three support the ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.2/upgrades/version_base"},"version_base")," parameter\nto define the compatibility level to use."),(0,o.mdx)("h3",{id:"code-example"},"Code example"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'from hydra import compose, initialize\nfrom omegaconf import OmegaConf\n\nif __name__ == "__main__":\n # context initialization\n with initialize(version_base=None, config_path="conf", job_name="test_app"):\n cfg = compose(config_name="config", overrides=["db=mysql", "db.user=me"])\n print(OmegaConf.to_yaml(cfg))\n\n # global initialization\n initialize(version_base=None, config_path="conf", job_name="test_app")\n cfg = compose(config_name="config", overrides=["db=mysql", "db.user=me"])\n print(OmegaConf.to_yaml(cfg))\n')),(0,o.mdx)("h3",{id:"api-documentation"},"API Documentation"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Compose API"',title:'"Compose','API"':!0},'def compose(\n config_name: Optional[str] = None,\n overrides: List[str] = [],\n return_hydra_config: bool = False,\n) -> DictConfig:\n """\n :param config_name: the name of the config\n (usually the file name without the .yaml extension)\n :param overrides: list of overrides for config file\n :param return_hydra_config: True to return the hydra config node in the result\n :return: the composed config\n """\n')),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Relative initialization"',title:'"Relative','initialization"':!0},'def initialize(\n version_base: Optional[str],\n config_path: Optional[str] = None,\n job_name: Optional[str] = "app",\n caller_stack_depth: int = 1,\n) -> None:\n """\n Initializes Hydra and add the config_path to the config search path.\n config_path is relative to the parent of the caller.\n Hydra detects the caller type automatically at runtime.\n\n Supported callers:\n - Python scripts\n - Python modules\n - Unit tests\n - Jupyter notebooks.\n :param version_base: compatibility level to use.\n :param config_path: path relative to the parent of the caller\n :param job_name: the value for hydra.job.name (By default it is automatically detected based on the caller)\n :param caller_stack_depth: stack depth of the caller, defaults to 1 (direct caller).\n """\n')),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Initialzing with config module"',title:'"Initialzing',with:!0,config:!0,'module"':!0},'def initialize_config_module(\n config_module: str,\n version_base: Optional[str],\n job_name: str = "app"\n) -> None:\n """\n Initializes Hydra and add the config_module to the config search path.\n The config module must be importable (an __init__.py must exist at its top level)\n :param config_module: absolute module name, for example "foo.bar.conf".\n :param version_base: compatibility level to use.\n :param job_name: the value for hydra.job.name (default is \'app\')\n """\n')),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Initialzing with config directory"',title:'"Initialzing',with:!0,config:!0,'directory"':!0},'def initialize_config_dir(\n config_dir: str,\n version_base: Optional[str],\n job_name: str = "app"\n) -> None:\n """\n Initializes Hydra and add an absolute config dir to the to the config search path.\n The config_dir is always a path on the file system and is must be an absolute path.\n Relative paths will result in an error.\n :param config_dir: absolute file system path\n :param version_base: compatibility level to use.\n :param job_name: the value for hydra.job.name (default is \'app\')\n """\n')))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1483e3dc.e1c4fedb.js b/assets/js/1483e3dc.e1c4fedb.js deleted file mode 100644 index 1e2fef2228..0000000000 --- a/assets/js/1483e3dc.e1c4fedb.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[7648],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>m,MDXProvider:()=>p,mdx:()=>f,useMDXComponents:()=>c,withMDXComponents:()=>d});var a=t(96540);function i(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function o(){return o=Object.assign||function(e){for(var n=1;n=0||(i[t]=e[t]);return i}(e,n);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(i[t]=e[t])}return i}var m=a.createContext({}),d=function(e){return function(n){var t=c(n.components);return a.createElement(e,o({},n,{components:t}))}},c=function(e){var n=a.useContext(m),t=n;return e&&(t="function"==typeof e?e(n):l(l({},n),e)),t},p=function(e){var n=c(e.components);return a.createElement(m.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},h=a.forwardRef((function(e,n){var t=e.components,i=e.mdxType,o=e.originalType,r=e.parentName,m=s(e,["components","mdxType","originalType","parentName"]),d=c(t),p=i,h=d["".concat(r,".").concat(p)]||d[p]||u[p]||o;return t?a.createElement(h,l(l({ref:n},m),{},{components:t})):a.createElement(h,l({ref:n},m))}));function f(e,n){var t=arguments,i=n&&n.mdxType;if("string"==typeof e||i){var o=t.length,r=new Array(o);r[0]=h;var l={};for(var s in n)hasOwnProperty.call(n,s)&&(l[s]=n[s]);l.originalType=e,l.mdxType="string"==typeof e?e:i,r[1]=l;for(var m=2;m{t.d(n,{A:()=>s,C:()=>m});var a=t(58168),i=t(96540),o=t(75489),r=t(44586),l=t(74098);function s(e){return i.createElement(o.default,(0,a.A)({},e,{to:(n=e.to,s=(0,l.useActiveVersion)(),(0,r.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==s?void 0:s.name)?t:"current"]+n),target:"_blank"}));var n,t,s}function m(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return i.createElement(s,e,i.createElement("span",null,"\xa0"),i.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},80487:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>m,default:()=>u,frontMatter:()=>s,metadata:()=>d,toc:()=>c});var a=t(58168),i=t(98587),o=(t(96540),t(15680)),r=t(49595),l=["components"],s={id:"compose_api",title:"Compose API",sidebar_label:"Compose API"},m=void 0,d={unversionedId:"advanced/compose_api",id:"version-1.2/advanced/compose_api",title:"Compose API",description:"The compose API can compose a config similarly to @hydra.main() anywhere in the code.",source:"@site/versioned_docs/version-1.2/advanced/compose_api.md",sourceDirName:"advanced",slug:"/advanced/compose_api",permalink:"/docs/1.2/advanced/compose_api",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/advanced/compose_api.md",tags:[],version:"1.2",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"compose_api",title:"Compose API",sidebar_label:"Compose API"},sidebar:"docs",previous:{title:"Structured Configs example",permalink:"/docs/1.2/advanced/instantiate_objects/structured_config"},next:{title:"Config Search Path",permalink:"/docs/1.2/advanced/search_path"}},c=[{value:"When to use the Compose API",id:"when-to-use-the-compose-api",children:[],level:3},{value:"Initialization methods",id:"initialization-methods",children:[],level:3},{value:"Code example",id:"code-example",children:[],level:3},{value:"API Documentation",id:"api-documentation",children:[],level:3}],p={toc:c};function u(e){var n=e.components,t=(0,i.A)(e,l);return(0,o.mdx)("wrapper",(0,a.A)({},p,t,{components:n,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"The compose API can compose a config similarly to ",(0,o.mdx)("inlineCode",{parentName:"p"},"@hydra.main()")," anywhere in the code.",(0,o.mdx)("br",{parentName:"p"}),"\n","Prior to calling compose(), you have to initialize Hydra: This can be done by using the standard ",(0,o.mdx)("inlineCode",{parentName:"p"},"@hydra.main()"),"\nor by calling one of the initialization methods listed below."),(0,o.mdx)("h3",{id:"when-to-use-the-compose-api"},"When to use the Compose API"),(0,o.mdx)("p",null,"The Compose API is useful when ",(0,o.mdx)("inlineCode",{parentName:"p"},"@hydra.main()")," is not applicable.\nFor example:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"Inside a Jupyter notebook (",(0,o.mdx)("a",{parentName:"li",href:"/docs/1.2/advanced/jupyter_notebooks"},"Example"),")"),(0,o.mdx)("li",{parentName:"ul"},"Inside a unit test (",(0,o.mdx)("a",{parentName:"li",href:"/docs/1.2/advanced/unit_testing"},"Example"),")"),(0,o.mdx)("li",{parentName:"ul"},"In parts of your application that does not have access to the command line (",(0,o.mdx)(r.A,{to:"examples/advanced/ad_hoc_composition",mdxType:"GithubLink"},"Example"),")."),(0,o.mdx)("li",{parentName:"ul"},"To compose multiple configuration objects (",(0,o.mdx)(r.A,{to:"examples/advanced/ray_example/ray_compose_example.py",mdxType:"GithubLink"},"Example with Ray"),").")),(0,o.mdx)("div",{class:"alert alert--info",role:"alert"},"Please avoid using the Compose API in cases where ",(0,o.mdx)("b",null,"@hydra.main()")," can be used. Doing so forfeits many of the benefits of Hydra (e.g., Tab completion, Multirun, Working directory management, Logging management and more)"),(0,o.mdx)("h3",{id:"initialization-methods"},"Initialization methods"),(0,o.mdx)("p",null,"There are 3 initialization methods:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"initialize()"),": Initialize with a config path relative to the caller"),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"initialize_config_module()")," : Initialize with config_module (absolute)"),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"initialize_config_dir()")," : Initialize with a config_dir on the file system (absolute)")),(0,o.mdx)("p",null,"All 3 can be used as methods or contexts.\nWhen used as methods, they are initializing Hydra globally and should only be called once.\nWhen used as contexts, they are initializing Hydra within the context can be used multiple times.\nLike ",(0,o.mdx)("b",null,"@hydra.main()")," all three support the ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.2/upgrades/version_base"},"version_base")," parameter\nto define the compatibility level to use."),(0,o.mdx)("h3",{id:"code-example"},"Code example"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'from hydra import compose, initialize\nfrom omegaconf import OmegaConf\n\nif __name__ == "__main__":\n # context initialization\n with initialize(version_base=None, config_path="conf", job_name="test_app"):\n cfg = compose(config_name="config", overrides=["db=mysql", "db.user=me"])\n print(OmegaConf.to_yaml(cfg))\n\n # global initialization\n initialize(version_base=None, config_path="conf", job_name="test_app")\n cfg = compose(config_name="config", overrides=["db=mysql", "db.user=me"])\n print(OmegaConf.to_yaml(cfg))\n')),(0,o.mdx)("h3",{id:"api-documentation"},"API Documentation"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Compose API"',title:'"Compose','API"':!0},'def compose(\n config_name: Optional[str] = None,\n overrides: List[str] = [],\n return_hydra_config: bool = False,\n) -> DictConfig:\n """\n :param config_name: the name of the config\n (usually the file name without the .yaml extension)\n :param overrides: list of overrides for config file\n :param return_hydra_config: True to return the hydra config node in the result\n :return: the composed config\n """\n')),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Relative initialization"',title:'"Relative','initialization"':!0},'def initialize(\n version_base: Optional[str],\n config_path: Optional[str] = None,\n job_name: Optional[str] = "app",\n caller_stack_depth: int = 1,\n) -> None:\n """\n Initializes Hydra and add the config_path to the config search path.\n config_path is relative to the parent of the caller.\n Hydra detects the caller type automatically at runtime.\n\n Supported callers:\n - Python scripts\n - Python modules\n - Unit tests\n - Jupyter notebooks.\n :param version_base: compatibility level to use.\n :param config_path: path relative to the parent of the caller\n :param job_name: the value for hydra.job.name (By default it is automatically detected based on the caller)\n :param caller_stack_depth: stack depth of the caller, defaults to 1 (direct caller).\n """\n')),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Initialzing with config module"',title:'"Initialzing',with:!0,config:!0,'module"':!0},'def initialize_config_module(\n config_module: str,\n version_base: Optional[str],\n job_name: str = "app"\n) -> None:\n """\n Initializes Hydra and add the config_module to the config search path.\n The config module must be importable (an __init__.py must exist at its top level)\n :param config_module: absolute module name, for example "foo.bar.conf".\n :param version_base: compatibility level to use.\n :param job_name: the value for hydra.job.name (default is \'app\')\n """\n')),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Initialzing with config directory"',title:'"Initialzing',with:!0,config:!0,'directory"':!0},'def initialize_config_dir(\n config_dir: str,\n version_base: Optional[str],\n job_name: str = "app"\n) -> None:\n """\n Initializes Hydra and add an absolute config dir to the to the config search path.\n The config_dir is always a path on the file system and is must be an absolute path.\n Relative paths will result in an error.\n :param config_dir: absolute file system path\n :param version_base: compatibility level to use.\n :param job_name: the value for hydra.job.name (default is \'app\')\n """\n')))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1564a8d3.a78dfb19.js b/assets/js/1564a8d3.a78dfb19.js deleted file mode 100644 index 4ee16d1587..0000000000 --- a/assets/js/1564a8d3.a78dfb19.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[5687],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>m,MDXProvider:()=>c,mdx:()=>y,useMDXComponents:()=>s,withMDXComponents:()=>p});var r=a(96540);function t(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function l(){return l=Object.assign||function(e){for(var n=1;n=0||(t[a]=e[a]);return t}(e,n);if(Object.getOwnPropertySymbols){var l=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(t[a]=e[a])}return t}var m=r.createContext({}),p=function(e){return function(n){var a=s(n.components);return r.createElement(e,l({},n,{components:a}))}},s=function(e){var n=r.useContext(m),a=n;return e&&(a="function"==typeof e?e(n):o(o({},n),e)),a},c=function(e){var n=s(e.components);return r.createElement(m.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},h=r.forwardRef((function(e,n){var a=e.components,t=e.mdxType,l=e.originalType,i=e.parentName,m=d(e,["components","mdxType","originalType","parentName"]),p=s(a),c=t,h=p["".concat(i,".").concat(c)]||p[c]||u[c]||l;return a?r.createElement(h,o(o({ref:n},m),{},{components:a})):r.createElement(h,o({ref:n},m))}));function y(e,n){var a=arguments,t=n&&n.mdxType;if("string"==typeof e||t){var l=a.length,i=new Array(l);i[0]=h;var o={};for(var d in n)hasOwnProperty.call(n,d)&&(o[d]=n[d]);o.originalType=e,o.mdxType="string"==typeof e?e:t,i[1]=o;for(var m=2;m{a.d(n,{A:()=>d,C:()=>m});var r=a(58168),t=a(96540),l=a(75489),i=a(44586),o=a(74098);function d(e){return t.createElement(l.default,(0,r.A)({},e,{to:(n=e.to,d=(0,o.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(a=null==d?void 0:d.name)?a:"current"]+n),target:"_blank"}));var n,a,d}function m(e){var n,a=null!=(n=e.text)?n:"Example (Click Here)";return t.createElement(d,e,t.createElement("span",null,"\xa0"),t.createElement("img",{src:"https://img.shields.io/badge/-"+a+"-informational",alt:"Example (Click Here)"}))}},39725:(e,n,a)=>{a.r(n),a.d(n,{contentTitle:()=>m,default:()=>u,frontMatter:()=>d,metadata:()=>p,toc:()=>s});var r=a(58168),t=a(98587),l=(a(96540),a(15680)),i=a(49595),o=["components"],d={id:"ray_launcher",title:"Ray Launcher plugin",sidebar_label:"Ray Launcher plugin"},m=void 0,p={unversionedId:"plugins/ray_launcher",id:"version-1.2/plugins/ray_launcher",title:"Ray Launcher plugin",description:"PyPI",source:"@site/versioned_docs/version-1.2/plugins/ray_launcher.md",sourceDirName:"plugins",slug:"/plugins/ray_launcher",permalink:"/docs/1.2/plugins/ray_launcher",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/plugins/ray_launcher.md",tags:[],version:"1.2",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"ray_launcher",title:"Ray Launcher plugin",sidebar_label:"Ray Launcher plugin"},sidebar:"docs",previous:{title:"Joblib Launcher plugin",permalink:"/docs/1.2/plugins/joblib_launcher"},next:{title:"RQ Launcher plugin",permalink:"/docs/1.2/plugins/rq_launcher"}},s=[{value:"Installation",id:"installation",children:[],level:3},{value:"Usage",id:"usage",children:[],level:3},{value:"ray_aws launcher",id:"ray_aws-launcher",children:[{value:"Examples",id:"examples",children:[{value:"Manage Cluster LifeCycle",id:"manage-cluster-lifecycle",children:[],level:5},{value:"Configure Ray Logging",id:"configure-ray-logging",children:[],level:5}],level:4}],level:3},{value:"ray launcher",id:"ray-launcher",children:[],level:3},{value:"Configure ray.init() and ray.remote()",id:"configure-rayinit-and-rayremote",children:[],level:3}],c={toc:s};function u(e){var n=e.components,a=(0,t.A)(e,o);return(0,l.mdx)("wrapper",(0,r.A)({},c,a,{components:n,mdxType:"MDXLayout"}),(0,l.mdx)("p",null,(0,l.mdx)("a",{parentName:"p",href:"https://pypi.org/project/hydra-ray-launcher/"},(0,l.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/v/hydra-ray-launcher",alt:"PyPI"})),"\n",(0,l.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/l/hydra-ray-launcher",alt:"PyPI - License"}),"\n",(0,l.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/pyversions/hydra-ray-launcher",alt:"PyPI - Python Version"}),"\n",(0,l.mdx)("a",{parentName:"p",href:"https://pypistats.org/packages/hydra-ray-launcher"},(0,l.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/dm/hydra-ray-launcher.svg",alt:"PyPI - Downloads"})),(0,l.mdx)(i.C,{text:"Example application",to:"plugins/hydra_ray_launcher/examples",mdxType:"ExampleGithubLink"}),(0,l.mdx)(i.C,{text:"Plugin source",to:"plugins/hydra_ray_launcher",mdxType:"ExampleGithubLink"})),(0,l.mdx)("p",null,"The Ray Launcher plugin provides 2 launchers: ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray_aws")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray"),".\n",(0,l.mdx)("inlineCode",{parentName:"p"},"ray_aws")," launches jobs remotely on AWS and is built on top of ",(0,l.mdx)("a",{parentName:"p",href:"https://docs.ray.io/en/releases-1.3.0/cluster/sdk.html"},"ray autoscaler sdk"),". ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray")," launches jobs on your local machine or existing ray cluster. "),(0,l.mdx)("h3",{id:"installation"},"Installation"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ pip install hydra-ray-launcher --upgrade\n")),(0,l.mdx)("h3",{id:"usage"},"Usage"),(0,l.mdx)("p",null,"Once installed, add ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra/launcher=ray_aws")," or ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra/launcher=ray")," to your command line. Alternatively, override ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra/launcher")," in your config:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - override hydra/launcher: ray_aws\n")),(0,l.mdx)("p",null,"There are several standard approaches for configuring plugins. Check ",(0,l.mdx)("a",{parentName:"p",href:"/docs/1.2/patterns/configuring_plugins"},"this page")," for more information."),(0,l.mdx)("h3",{id:"ray_aws-launcher"},(0,l.mdx)("inlineCode",{parentName:"h3"},"ray_aws")," launcher"),(0,l.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,l.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,l.mdx)("h5",{parentName:"div"},(0,l.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,l.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,l.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,l.mdx)("div",{parentName:"div",className:"admonition-content"},(0,l.mdx)("p",{parentName:"div"},(0,l.mdx)("inlineCode",{parentName:"p"},"ray_aws")," launcher is built on top of ray's ",(0,l.mdx)("a",{parentName:"p",href:"https://docs.ray.io/en/releases-1.3.0/cluster/sdk.html"},"autoscaler sdk"),". To get started, you need to\n",(0,l.mdx)("a",{parentName:"p",href:"https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html"},"config your AWS credentials"),".\n",(0,l.mdx)("inlineCode",{parentName:"p"},"ray autoscaler sdk")," expects your AWS credentials have certain permissions for ",(0,l.mdx)("a",{parentName:"p",href:"https://aws.amazon.com/ec2"},(0,l.mdx)("inlineCode",{parentName:"a"},"EC2"))," and ",(0,l.mdx)("a",{parentName:"p",href:"https://aws.amazon.com/iam"},(0,l.mdx)("inlineCode",{parentName:"a"},"IAM")),". Read ",(0,l.mdx)("a",{parentName:"p",href:"https://github.com/ray-project/ray/issues/9327"},"this")," for more information."))),(0,l.mdx)("p",null,(0,l.mdx)("inlineCode",{parentName:"p"},"ray autoscaler sdk")," expects a configuration for the EC2 cluster; we've schematized the configs in ",(0,l.mdx)(i.A,{to:"plugins/hydra_ray_launcher/hydra_plugins/hydra_ray_launcher/_config.py",mdxType:"GithubLink"},"here")),(0,l.mdx)("details",null,(0,l.mdx)("summary",null,"Discover ray_aws launcher's config"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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\nenv_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\nray:\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 initial_workers: 0\n autoscaling_mode: default\n target_utilization_fraction: 0.8\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\nstop_cluster: true\nsync_up:\n source_dir: null\n target_dir: null\n include: []\n exclude: []\nsync_down:\n source_dir: null\n target_dir: null\n include: []\n exclude: []\nlogging:\n log_style: auto\n color_mode: auto\n verbosity: 0\ncreate_update_cluster:\n no_restart: false\n restart_only: false\n no_config_cache: false\nteardown_cluster:\n workers_only: false\n keep_min_workers: false\n"))),(0,l.mdx)("h4",{id:"examples"},"Examples"),(0,l.mdx)("p",null,"The following examples can be found ",(0,l.mdx)(i.A,{to:"plugins/hydra_ray_launcher/examples",mdxType:"GithubLink"},"here"),"."),(0,l.mdx)("details",null,(0,l.mdx)("summary",null,"Simple app"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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\nCluster: default\n...\nINFO 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)\nDestroying cluster. Confirm [y/N]: y [automatic, due to --yes]\n...\nNo nodes remaining.\n\n"))),(0,l.mdx)("details",null,(0,l.mdx)("summary",null,"Upload & Download from remote cluster"),(0,l.mdx)("p",null,"If your application is dependent on multiple modules, you can configure ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.sync_up")," to upload dependency modules to the remote cluster.\nYou can also configure ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.sync_down")," to download output from remote cluster if needed. This functionality is built on top of ",(0,l.mdx)("inlineCode",{parentName:"p"},"rsync"),", ",(0,l.mdx)("inlineCode",{parentName:"p"},"include")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"exclude")," is consistent with how it works in ",(0,l.mdx)("inlineCode",{parentName:"p"},"rsync"),"."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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\nCluster: default\n...\nINFO 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\nLoaded cached provider configuration\n...\n[HYDRA] Output: receiving file list ... done\n16-32-25/\n16-32-25/0/\n16-32-25/0/checkpoint/\n16-32-25/0/checkpoint/checkpoint_1.pt\n16-32-25/1/\n16-32-25/1/checkpoint/\n16-32-25/1/checkpoint/checkpoint_2.pt\n16-32-25/2/\n16-32-25/2/checkpoint/\n16-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)\nDestroying cluster. Confirm [y/N]: y [automatic, due to --yes]\n...\nNo nodes remaining.\n\n"))),(0,l.mdx)("h5",{id:"manage-cluster-lifecycle"},"Manage Cluster LifeCycle"),(0,l.mdx)("p",null,"You can manage the Ray EC2 cluster lifecycle by configuring the flags provided by the plugin:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Default setting (no need to specify on commandline): delete cluster after job finishes remotely:"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.stop_cluster=true\nhydra.launcher.ray.cluster.provider.cache_stopped_nodes=false\nhydra.launcher.teardown_cluster.workers_only=false\nhydra.launcher.teardown_cluster.keep_min_workers=false\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Keep cluster running after jobs finishes remotely"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.stop_cluster=false\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Power off EC2 instances and control node termination using ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.cluster.provider.cache_stopped_nodes"),"\nand ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.teardown_cluster.workers_only")),(0,l.mdx)("table",{parentName:"li"},(0,l.mdx)("thead",{parentName:"table"},(0,l.mdx)("tr",{parentName:"thead"},(0,l.mdx)("th",{parentName:"tr",align:null},"cache_stopped_nodes"),(0,l.mdx)("th",{parentName:"tr",align:null},"workers_only"),(0,l.mdx)("th",{parentName:"tr",align:null},"behavior"))),(0,l.mdx)("tbody",{parentName:"table"},(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"All nodes are terminated")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"Keeps head node running and terminates only worker node")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"Keeps both head node and worker node and stops both of them")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"Keeps both head node and worker node and stops only worker node"))))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Keep ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.cluster.min_workers")," worker nodes\nand delete the rest of the worker nodes"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.teardown_cluster.keep_min_workers=true\n")))),(0,l.mdx)("p",null,"Additionally, you can configure how to create or update the cluster:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Default config: run setup commands, restart Ray and use\nthe config cache if available"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.create_update_cluster.no_restart=false\nhydra.launcher.create_update_cluster.restart_only=false\nhydra.launcher.create_update_cluster.no_config_cache=false\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Skip restarting Ray services when updating the cluster config"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.create_update_cluster.no_restart=true\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Skip running setup commands and only restart Ray (cannot be used with\n",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.create_update_cluster.no_restart"),")"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.create_update_cluster.restart_only=true\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Fully resolve all environment settings from the cloud provider again"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.create_update_cluster.no_config_cache=true\n")))),(0,l.mdx)("h5",{id:"configure-ray-logging"},"Configure Ray Logging"),(0,l.mdx)("p",null,"You can manage Ray specific logging by configuring the flags provided by the plugin:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Default config: use minimal verbosity and automatically\ndetect whether to use pretty-print and color mode"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},'hydra.launcher.logging.log_style="auto"\nhydra.launcher.logging.color_mode="auto"\nhydra.launcher.logging.verbosity=0\n'))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Disable pretty-print"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},'hydra.launcher.logging.log_style="record"\n'))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Disable color mode"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},'hydra.launcher.logging.color_mode="false"\n'))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Increase Ray logging verbosity"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.logging.verbosity=3\n")))),(0,l.mdx)("h3",{id:"ray-launcher"},(0,l.mdx)("inlineCode",{parentName:"h3"},"ray")," launcher"),(0,l.mdx)("p",null,(0,l.mdx)("inlineCode",{parentName:"p"},"ray")," launcher lets you launch application on your ray cluster or local machine. You can easily config how your jobs are executed by changing ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray")," launcher's configuration here\n",(0,l.mdx)("inlineCode",{parentName:"p"},"~/hydra/plugins/hydra_ray_launcher/hydra_plugins/hydra_ray_launcher/conf/hydra/launcher/ray.yaml")),(0,l.mdx)("p",null," The ",(0,l.mdx)(i.A,{to:"plugins/hydra_ray_launcher/examples/simple",mdxType:"GithubLink"},"example application")," starts a new ray cluster."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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")),(0,l.mdx)("p",null,"You can run the example application on your existing ray cluster as well by overriding ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.init.address"),":"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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")),(0,l.mdx)("h3",{id:"configure-rayinit-and-rayremote"},"Configure ",(0,l.mdx)("inlineCode",{parentName:"h3"},"ray.init()")," and ",(0,l.mdx)("inlineCode",{parentName:"h3"},"ray.remote()")),(0,l.mdx)("p",null,"Ray launcher is built on top of ",(0,l.mdx)("a",{parentName:"p",href:"https://docs.ray.io/en/master/package-ref.html?highlight=ray.remote#ray-init"},(0,l.mdx)("inlineCode",{parentName:"a"},"ray.init()")),"\nand ",(0,l.mdx)("a",{parentName:"p",href:"https://docs.ray.io/en/master/package-ref.html?highlight=ray.remote#ray-remote"},(0,l.mdx)("inlineCode",{parentName:"a"},"ray.remote()")),".\nYou can configure ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray")," by overriding ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.init")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.remote"),".\nCheck out an ",(0,l.mdx)(i.A,{to:"plugins/hydra_ray_launcher/examples/simple/config.yaml",mdxType:"GithubLink"},"example config"),"."))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1564a8d3.aea91821.js b/assets/js/1564a8d3.aea91821.js new file mode 100644 index 0000000000..623416797c --- /dev/null +++ b/assets/js/1564a8d3.aea91821.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[5687],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>m,MDXProvider:()=>c,mdx:()=>y,useMDXComponents:()=>s,withMDXComponents:()=>p});var r=a(96540);function t(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function l(){return l=Object.assign||function(e){for(var n=1;n=0||(t[a]=e[a]);return t}(e,n);if(Object.getOwnPropertySymbols){var l=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(t[a]=e[a])}return t}var m=r.createContext({}),p=function(e){return function(n){var a=s(n.components);return r.createElement(e,l({},n,{components:a}))}},s=function(e){var n=r.useContext(m),a=n;return e&&(a="function"==typeof e?e(n):o(o({},n),e)),a},c=function(e){var n=s(e.components);return r.createElement(m.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},h=r.forwardRef((function(e,n){var a=e.components,t=e.mdxType,l=e.originalType,i=e.parentName,m=d(e,["components","mdxType","originalType","parentName"]),p=s(a),c=t,h=p["".concat(i,".").concat(c)]||p[c]||u[c]||l;return a?r.createElement(h,o(o({ref:n},m),{},{components:a})):r.createElement(h,o({ref:n},m))}));function y(e,n){var a=arguments,t=n&&n.mdxType;if("string"==typeof e||t){var l=a.length,i=new Array(l);i[0]=h;var o={};for(var d in n)hasOwnProperty.call(n,d)&&(o[d]=n[d]);o.originalType=e,o.mdxType="string"==typeof e?e:t,i[1]=o;for(var m=2;m{a.d(n,{A:()=>d,C:()=>m});var r=a(58168),t=a(96540),l=a(75489),i=a(44586),o=a(74098);function d(e){return t.createElement(l.default,(0,r.A)({},e,{to:(n=e.to,d=(0,o.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(a=null==d?void 0:d.name)?a:"current"]+n),target:"_blank"}));var n,a,d}function m(e){var n,a=null!=(n=e.text)?n:"Example (Click Here)";return t.createElement(d,e,t.createElement("span",null,"\xa0"),t.createElement("img",{src:"https://img.shields.io/badge/-"+a+"-informational",alt:"Example (Click Here)"}))}},39725:(e,n,a)=>{a.r(n),a.d(n,{contentTitle:()=>m,default:()=>u,frontMatter:()=>d,metadata:()=>p,toc:()=>s});var r=a(58168),t=a(98587),l=(a(96540),a(15680)),i=a(49595),o=["components"],d={id:"ray_launcher",title:"Ray Launcher plugin",sidebar_label:"Ray Launcher plugin"},m=void 0,p={unversionedId:"plugins/ray_launcher",id:"version-1.2/plugins/ray_launcher",title:"Ray Launcher plugin",description:"PyPI",source:"@site/versioned_docs/version-1.2/plugins/ray_launcher.md",sourceDirName:"plugins",slug:"/plugins/ray_launcher",permalink:"/docs/1.2/plugins/ray_launcher",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/plugins/ray_launcher.md",tags:[],version:"1.2",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"ray_launcher",title:"Ray Launcher plugin",sidebar_label:"Ray Launcher plugin"},sidebar:"docs",previous:{title:"Joblib Launcher plugin",permalink:"/docs/1.2/plugins/joblib_launcher"},next:{title:"RQ Launcher plugin",permalink:"/docs/1.2/plugins/rq_launcher"}},s=[{value:"Installation",id:"installation",children:[],level:3},{value:"Usage",id:"usage",children:[],level:3},{value:"ray_aws launcher",id:"ray_aws-launcher",children:[{value:"Examples",id:"examples",children:[{value:"Manage Cluster LifeCycle",id:"manage-cluster-lifecycle",children:[],level:5},{value:"Configure Ray Logging",id:"configure-ray-logging",children:[],level:5}],level:4}],level:3},{value:"ray launcher",id:"ray-launcher",children:[],level:3},{value:"Configure ray.init() and ray.remote()",id:"configure-rayinit-and-rayremote",children:[],level:3}],c={toc:s};function u(e){var n=e.components,a=(0,t.A)(e,o);return(0,l.mdx)("wrapper",(0,r.A)({},c,a,{components:n,mdxType:"MDXLayout"}),(0,l.mdx)("p",null,(0,l.mdx)("a",{parentName:"p",href:"https://pypi.org/project/hydra-ray-launcher/"},(0,l.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/v/hydra-ray-launcher",alt:"PyPI"})),"\n",(0,l.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/l/hydra-ray-launcher",alt:"PyPI - License"}),"\n",(0,l.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/pyversions/hydra-ray-launcher",alt:"PyPI - Python Version"}),"\n",(0,l.mdx)("a",{parentName:"p",href:"https://pypistats.org/packages/hydra-ray-launcher"},(0,l.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/dm/hydra-ray-launcher.svg",alt:"PyPI - Downloads"})),(0,l.mdx)(i.C,{text:"Example application",to:"plugins/hydra_ray_launcher/examples",mdxType:"ExampleGithubLink"}),(0,l.mdx)(i.C,{text:"Plugin source",to:"plugins/hydra_ray_launcher",mdxType:"ExampleGithubLink"})),(0,l.mdx)("p",null,"The Ray Launcher plugin provides 2 launchers: ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray_aws")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray"),".\n",(0,l.mdx)("inlineCode",{parentName:"p"},"ray_aws")," launches jobs remotely on AWS and is built on top of ",(0,l.mdx)("a",{parentName:"p",href:"https://docs.ray.io/en/releases-1.3.0/cluster/sdk.html"},"ray autoscaler sdk"),". ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray")," launches jobs on your local machine or existing ray cluster. "),(0,l.mdx)("h3",{id:"installation"},"Installation"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ pip install hydra-ray-launcher --upgrade\n")),(0,l.mdx)("h3",{id:"usage"},"Usage"),(0,l.mdx)("p",null,"Once installed, add ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra/launcher=ray_aws")," or ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra/launcher=ray")," to your command line. Alternatively, override ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra/launcher")," in your config:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - override hydra/launcher: ray_aws\n")),(0,l.mdx)("p",null,"There are several standard approaches for configuring plugins. Check ",(0,l.mdx)("a",{parentName:"p",href:"/docs/1.2/patterns/configuring_plugins"},"this page")," for more information."),(0,l.mdx)("h3",{id:"ray_aws-launcher"},(0,l.mdx)("inlineCode",{parentName:"h3"},"ray_aws")," launcher"),(0,l.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,l.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,l.mdx)("h5",{parentName:"div"},(0,l.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,l.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,l.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,l.mdx)("div",{parentName:"div",className:"admonition-content"},(0,l.mdx)("p",{parentName:"div"},(0,l.mdx)("inlineCode",{parentName:"p"},"ray_aws")," launcher is built on top of ray's ",(0,l.mdx)("a",{parentName:"p",href:"https://docs.ray.io/en/releases-1.3.0/cluster/sdk.html"},"autoscaler sdk"),". To get started, you need to\n",(0,l.mdx)("a",{parentName:"p",href:"https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html"},"config your AWS credentials"),".\n",(0,l.mdx)("inlineCode",{parentName:"p"},"ray autoscaler sdk")," expects your AWS credentials have certain permissions for ",(0,l.mdx)("a",{parentName:"p",href:"https://aws.amazon.com/ec2"},(0,l.mdx)("inlineCode",{parentName:"a"},"EC2"))," and ",(0,l.mdx)("a",{parentName:"p",href:"https://aws.amazon.com/iam"},(0,l.mdx)("inlineCode",{parentName:"a"},"IAM")),". Read ",(0,l.mdx)("a",{parentName:"p",href:"https://github.com/ray-project/ray/issues/9327"},"this")," for more information."))),(0,l.mdx)("p",null,(0,l.mdx)("inlineCode",{parentName:"p"},"ray autoscaler sdk")," expects a configuration for the EC2 cluster; we've schematized the configs in ",(0,l.mdx)(i.A,{to:"plugins/hydra_ray_launcher/hydra_plugins/hydra_ray_launcher/_config.py",mdxType:"GithubLink"},"here")),(0,l.mdx)("details",null,(0,l.mdx)("summary",null,"Discover ray_aws launcher's config"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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\nenv_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\nray:\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 initial_workers: 0\n autoscaling_mode: default\n target_utilization_fraction: 0.8\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\nstop_cluster: true\nsync_up:\n source_dir: null\n target_dir: null\n include: []\n exclude: []\nsync_down:\n source_dir: null\n target_dir: null\n include: []\n exclude: []\nlogging:\n log_style: auto\n color_mode: auto\n verbosity: 0\ncreate_update_cluster:\n no_restart: false\n restart_only: false\n no_config_cache: false\nteardown_cluster:\n workers_only: false\n keep_min_workers: false\n"))),(0,l.mdx)("h4",{id:"examples"},"Examples"),(0,l.mdx)("p",null,"The following examples can be found ",(0,l.mdx)(i.A,{to:"plugins/hydra_ray_launcher/examples",mdxType:"GithubLink"},"here"),"."),(0,l.mdx)("details",null,(0,l.mdx)("summary",null,"Simple app"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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\nCluster: default\n...\nINFO 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)\nDestroying cluster. Confirm [y/N]: y [automatic, due to --yes]\n...\nNo nodes remaining.\n\n"))),(0,l.mdx)("details",null,(0,l.mdx)("summary",null,"Upload & Download from remote cluster"),(0,l.mdx)("p",null,"If your application is dependent on multiple modules, you can configure ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.sync_up")," to upload dependency modules to the remote cluster.\nYou can also configure ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.sync_down")," to download output from remote cluster if needed. This functionality is built on top of ",(0,l.mdx)("inlineCode",{parentName:"p"},"rsync"),", ",(0,l.mdx)("inlineCode",{parentName:"p"},"include")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"exclude")," is consistent with how it works in ",(0,l.mdx)("inlineCode",{parentName:"p"},"rsync"),"."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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\nCluster: default\n...\nINFO 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\nLoaded cached provider configuration\n...\n[HYDRA] Output: receiving file list ... done\n16-32-25/\n16-32-25/0/\n16-32-25/0/checkpoint/\n16-32-25/0/checkpoint/checkpoint_1.pt\n16-32-25/1/\n16-32-25/1/checkpoint/\n16-32-25/1/checkpoint/checkpoint_2.pt\n16-32-25/2/\n16-32-25/2/checkpoint/\n16-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)\nDestroying cluster. Confirm [y/N]: y [automatic, due to --yes]\n...\nNo nodes remaining.\n\n"))),(0,l.mdx)("h5",{id:"manage-cluster-lifecycle"},"Manage Cluster LifeCycle"),(0,l.mdx)("p",null,"You can manage the Ray EC2 cluster lifecycle by configuring the flags provided by the plugin:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Default setting (no need to specify on commandline): delete cluster after job finishes remotely:"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.stop_cluster=true\nhydra.launcher.ray.cluster.provider.cache_stopped_nodes=false\nhydra.launcher.teardown_cluster.workers_only=false\nhydra.launcher.teardown_cluster.keep_min_workers=false\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Keep cluster running after jobs finishes remotely"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.stop_cluster=false\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Power off EC2 instances and control node termination using ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.cluster.provider.cache_stopped_nodes"),"\nand ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.teardown_cluster.workers_only")),(0,l.mdx)("table",{parentName:"li"},(0,l.mdx)("thead",{parentName:"table"},(0,l.mdx)("tr",{parentName:"thead"},(0,l.mdx)("th",{parentName:"tr",align:null},"cache_stopped_nodes"),(0,l.mdx)("th",{parentName:"tr",align:null},"workers_only"),(0,l.mdx)("th",{parentName:"tr",align:null},"behavior"))),(0,l.mdx)("tbody",{parentName:"table"},(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"All nodes are terminated")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"Keeps head node running and terminates only worker node")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"Keeps both head node and worker node and stops both of them")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"Keeps both head node and worker node and stops only worker node"))))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Keep ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.cluster.min_workers")," worker nodes\nand delete the rest of the worker nodes"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.teardown_cluster.keep_min_workers=true\n")))),(0,l.mdx)("p",null,"Additionally, you can configure how to create or update the cluster:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Default config: run setup commands, restart Ray and use\nthe config cache if available"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.create_update_cluster.no_restart=false\nhydra.launcher.create_update_cluster.restart_only=false\nhydra.launcher.create_update_cluster.no_config_cache=false\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Skip restarting Ray services when updating the cluster config"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.create_update_cluster.no_restart=true\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Skip running setup commands and only restart Ray (cannot be used with\n",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.create_update_cluster.no_restart"),")"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.create_update_cluster.restart_only=true\n"))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Fully resolve all environment settings from the cloud provider again"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.create_update_cluster.no_config_cache=true\n")))),(0,l.mdx)("h5",{id:"configure-ray-logging"},"Configure Ray Logging"),(0,l.mdx)("p",null,"You can manage Ray specific logging by configuring the flags provided by the plugin:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Default config: use minimal verbosity and automatically\ndetect whether to use pretty-print and color mode"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},'hydra.launcher.logging.log_style="auto"\nhydra.launcher.logging.color_mode="auto"\nhydra.launcher.logging.verbosity=0\n'))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Disable pretty-print"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},'hydra.launcher.logging.log_style="record"\n'))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Disable color mode"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},'hydra.launcher.logging.color_mode="false"\n'))),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("p",{parentName:"li"},"Increase Ray logging verbosity"),(0,l.mdx)("pre",{parentName:"li"},(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"hydra.launcher.logging.verbosity=3\n")))),(0,l.mdx)("h3",{id:"ray-launcher"},(0,l.mdx)("inlineCode",{parentName:"h3"},"ray")," launcher"),(0,l.mdx)("p",null,(0,l.mdx)("inlineCode",{parentName:"p"},"ray")," launcher lets you launch application on your ray cluster or local machine. You can easily config how your jobs are executed by changing ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray")," launcher's configuration here\n",(0,l.mdx)("inlineCode",{parentName:"p"},"~/hydra/plugins/hydra_ray_launcher/hydra_plugins/hydra_ray_launcher/conf/hydra/launcher/ray.yaml")),(0,l.mdx)("p",null," The ",(0,l.mdx)(i.A,{to:"plugins/hydra_ray_launcher/examples/simple",mdxType:"GithubLink"},"example application")," starts a new ray cluster."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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")),(0,l.mdx)("p",null,"You can run the example application on your existing ray cluster as well by overriding ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.init.address"),":"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ 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")),(0,l.mdx)("h3",{id:"configure-rayinit-and-rayremote"},"Configure ",(0,l.mdx)("inlineCode",{parentName:"h3"},"ray.init()")," and ",(0,l.mdx)("inlineCode",{parentName:"h3"},"ray.remote()")),(0,l.mdx)("p",null,"Ray launcher is built on top of ",(0,l.mdx)("a",{parentName:"p",href:"https://docs.ray.io/en/master/package-ref.html?highlight=ray.remote#ray-init"},(0,l.mdx)("inlineCode",{parentName:"a"},"ray.init()")),"\nand ",(0,l.mdx)("a",{parentName:"p",href:"https://docs.ray.io/en/master/package-ref.html?highlight=ray.remote#ray-remote"},(0,l.mdx)("inlineCode",{parentName:"a"},"ray.remote()")),".\nYou can configure ",(0,l.mdx)("inlineCode",{parentName:"p"},"ray")," by overriding ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.init")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra.launcher.ray.remote"),".\nCheck out an ",(0,l.mdx)(i.A,{to:"plugins/hydra_ray_launcher/examples/simple/config.yaml",mdxType:"GithubLink"},"example config"),"."))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/16568db6.861050ec.js b/assets/js/16568db6.861050ec.js new file mode 100644 index 0000000000..540df8e972 --- /dev/null +++ b/assets/js/16568db6.861050ec.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[2175],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>d,MDXProvider:()=>u,mdx:()=>h,useMDXComponents:()=>p,withMDXComponents:()=>s});var a=n(96540);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var d=a.createContext({}),s=function(e){return function(t){var n=p(t.components);return a.createElement(e,o({},t,{components:n}))}},p=function(e){var t=a.useContext(d),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},u=function(e){var t=p(e.components);return a.createElement(d.Provider,{value:t},e.children)},c={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},f=a.forwardRef((function(e,t){var n=e.components,r=e.mdxType,o=e.originalType,l=e.parentName,d=m(e,["components","mdxType","originalType","parentName"]),s=p(n),u=r,f=s["".concat(l,".").concat(u)]||s[u]||c[u]||o;return n?a.createElement(f,i(i({ref:t},d),{},{components:n})):a.createElement(f,i({ref:t},d))}));function h(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var o=n.length,l=new Array(o);l[0]=f;var i={};for(var m in t)hasOwnProperty.call(t,m)&&(i[m]=t[m]);i.originalType=e,i.mdxType="string"==typeof e?e:r,l[1]=i;for(var d=2;d{n.r(t),n.d(t,{contentTitle:()=>m,default:()=>u,frontMatter:()=>i,metadata:()=>d,toc:()=>s});var a=n(58168),r=n(98587),o=(n(96540),n(15680)),l=(n(86025),n(75489),["components"]),i={id:"intro",title:"Getting started",sidebar_label:"Getting started"},m=void 0,d={unversionedId:"intro",id:"version-1.3/intro",title:"Getting started",description:"Introduction",source:"@site/versioned_docs/version-1.3/intro.md",sourceDirName:".",slug:"/intro",permalink:"/docs/1.3/intro",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/intro.md",tags:[],version:"1.3",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"intro",title:"Getting started",sidebar_label:"Getting started"},sidebar:"docs",next:{title:"Tutorials intro",permalink:"/docs/1.3/tutorials/intro"}},s=[{value:"Introduction",id:"introduction",children:[{value:"Key features:",id:"key-features",children:[],level:3}],level:2},{value:"Versions",id:"versions",children:[],level:2},{value:"Quick start guide",id:"quick-start-guide",children:[{value:"Installation",id:"installation",children:[],level:3},{value:"Basic example",id:"basic-example",children:[],level:3},{value:"Composition example",id:"composition-example",children:[],level:3},{value:"Multirun",id:"multirun",children:[],level:3}],level:2},{value:"Other stuff",id:"other-stuff",children:[{value:"Community",id:"community",children:[],level:3},{value:"Citing Hydra",id:"citing-hydra",children:[],level:3}],level:2}],p={toc:s};function u(e){var t=e.components,n=(0,r.A)(e,l);return(0,o.mdx)("wrapper",(0,a.A)({},p,n,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)("h2",{id:"introduction"},"Introduction"),(0,o.mdx)("p",null,"Hydra is an open-source Python framework that simplifies the development of research and other complex applications.\nThe key feature is the ability to dynamically create a hierarchical configuration by composition and override it through config files and the command line.\nThe name Hydra comes from its ability to run multiple similar jobs - much like a Hydra with multiple heads."),(0,o.mdx)("h3",{id:"key-features"},"Key features:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"Hierarchical configuration composable from multiple sources"),(0,o.mdx)("li",{parentName:"ul"},"Configuration can be specified or overridden from the command line"),(0,o.mdx)("li",{parentName:"ul"},"Dynamic command line tab completion"),(0,o.mdx)("li",{parentName:"ul"},"Run your application locally or launch it to run remotely"),(0,o.mdx)("li",{parentName:"ul"},"Run multiple jobs with different arguments with a single command")),(0,o.mdx)("h2",{id:"versions"},"Versions"),(0,o.mdx)("p",null,"Hydra supports Linux, Mac and Windows.",(0,o.mdx)("br",{parentName:"p"}),"\n","Use the version switcher in the top bar to switch between documentation versions."),(0,o.mdx)("table",null,(0,o.mdx)("thead",{parentName:"table"},(0,o.mdx)("tr",{parentName:"thead"},(0,o.mdx)("th",{parentName:"tr",align:null}),(0,o.mdx)("th",{parentName:"tr",align:null},"Version"),(0,o.mdx)("th",{parentName:"tr",align:null},"Release notes"),(0,o.mdx)("th",{parentName:"tr",align:null},"Python Versions"))),(0,o.mdx)("tbody",{parentName:"table"},(0,o.mdx)("tr",{parentName:"tbody"},(0,o.mdx)("td",{parentName:"tr",align:null},"\u25ba"),(0,o.mdx)("td",{parentName:"tr",align:null},"1.3 (Stable)"),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v1.3.0"},"Release notes")),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("strong",{parentName:"td"},"3.6 - 3.11"))),(0,o.mdx)("tr",{parentName:"tbody"},(0,o.mdx)("td",{parentName:"tr",align:null}),(0,o.mdx)("td",{parentName:"tr",align:null},"1.2"),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v1.2.0"},"Release notes")),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("strong",{parentName:"td"},"3.6 - 3.10"))),(0,o.mdx)("tr",{parentName:"tbody"},(0,o.mdx)("td",{parentName:"tr",align:null}),(0,o.mdx)("td",{parentName:"tr",align:null},"1.1"),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v1.1.1"},"Release notes")),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("strong",{parentName:"td"},"3.6 - 3.9"))),(0,o.mdx)("tr",{parentName:"tbody"},(0,o.mdx)("td",{parentName:"tr",align:null}),(0,o.mdx)("td",{parentName:"tr",align:null},"1.0"),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v1.0.7"},"Release notes")),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("strong",{parentName:"td"},"3.6 - 3.8"))),(0,o.mdx)("tr",{parentName:"tbody"},(0,o.mdx)("td",{parentName:"tr",align:null}),(0,o.mdx)("td",{parentName:"tr",align:null},"0.11"),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v0.11.3"},"Release notes")),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("strong",{parentName:"td"},"2.7, 3.5 - 3.8"))))),(0,o.mdx)("h2",{id:"quick-start-guide"},"Quick start guide"),(0,o.mdx)("p",null,"This guide will show you some of the most important features you get by writing your application as a Hydra app.\nIf you only want to use Hydra for config composition, check out Hydra's ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.3/advanced/compose_api"},"compose API")," for an alternative.\nPlease also read the full ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.3/tutorials/basic/your_first_app/simple_cli"},"tutorial")," to gain a deeper understanding."),(0,o.mdx)("h3",{id:"installation"},"Installation"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-commandline"},"pip install hydra-core --upgrade\n")),(0,o.mdx)("h3",{id:"basic-example"},"Basic example"),(0,o.mdx)("p",null,"Config:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="conf/config.yaml"',title:'"conf/config.yaml"'},"db:\n driver: mysql\n user: omry\n pass: secret\n")),(0,o.mdx)("p",null,"Application:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'{4-6} title="my_app.py"',"{4-6}":!0,title:'"my_app.py"'},'import hydra\nfrom omegaconf import DictConfig, OmegaConf\n\n@hydra.main(version_base=None, config_path="conf", config_name="config")\ndef my_app(cfg : DictConfig) -> None:\n print(OmegaConf.to_yaml(cfg))\n\nif __name__ == "__main__":\n my_app()\n')),(0,o.mdx)("p",null,"You can learn more about OmegaConf ",(0,o.mdx)("a",{parentName:"p",href:"https://omegaconf.readthedocs.io/en/latest/usage.html#access-and-manipulation"},"here")," later."),(0,o.mdx)("p",null,(0,o.mdx)("inlineCode",{parentName:"p"},"config.yaml")," is loaded automatically when you run your application"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py\ndb:\n driver: mysql\n pass: secret\n user: omry\n")),(0,o.mdx)("p",null,"You can override values in the loaded config from the command line:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{4-5}","{4-5}":!0},"$ python my_app.py db.user=root db.pass=1234\ndb:\n driver: mysql\n user: root\n pass: 1234\n")),(0,o.mdx)("h3",{id:"composition-example"},"Composition example"),(0,o.mdx)("p",null,"You may want to alternate between two different databases. To support this create a ",(0,o.mdx)("inlineCode",{parentName:"p"},"config group")," named db,\nand place one config file for each alternative inside:\nThe directory structure of our application now looks like:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-text"},"\u251c\u2500\u2500 conf\n\u2502\xa0\xa0 \u251c\u2500\u2500 config.yaml\n\u2502\xa0\xa0 \u251c\u2500\u2500 db\n\u2502\xa0\xa0 \u2502\xa0\xa0 \u251c\u2500\u2500 mysql.yaml\n\u2502\xa0\xa0 \u2502\xa0\xa0 \u2514\u2500\u2500 postgresql.yaml\n\u2502\xa0\xa0 \u2514\u2500\u2500 __init__.py\n\u2514\u2500\u2500 my_app.py\n")),(0,o.mdx)("p",null,"Here is the new config:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="conf/config.yaml"',title:'"conf/config.yaml"'},"defaults:\n - db: mysql\n")),(0,o.mdx)("p",null,(0,o.mdx)("inlineCode",{parentName:"p"},"defaults")," is a special directive telling Hydra to use db/mysql.yaml when composing the configuration object.\nThe resulting cfg object is a composition of configs from defaults with configs specified in your ",(0,o.mdx)("inlineCode",{parentName:"p"},"config.yaml"),"."),(0,o.mdx)("p",null,"You can now choose which database configuration to use and override values from the command line: "),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py db=postgresql db.timeout=20\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 20\n user: postgres_user\n")),(0,o.mdx)("p",null,"You can have as many config groups as you need."),(0,o.mdx)("h3",{id:"multirun"},"Multirun"),(0,o.mdx)("p",null,"You can run your function multiple times with different configuration easily with the ",(0,o.mdx)("inlineCode",{parentName:"p"},"--multirun|-m")," flag."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre"},"$ python my_app.py --multirun db=mysql,postgresql\n[HYDRA] Sweep output dir : multirun/2020-01-09/01-16-29\n[HYDRA] Launching 2 jobs locally\n[HYDRA] #0 : db=mysql\ndb:\n driver: mysql\n pass: secret\n user: omry\n\n[HYDRA] #1 : db=postgresql\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 10\n user: postgres_user\n")),(0,o.mdx)("p",null,"There is a whole lot more to Hydra. Read the ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.3/tutorials/basic/your_first_app/simple_cli"},"tutorial")," to learn more."),(0,o.mdx)("h2",{id:"other-stuff"},"Other stuff"),(0,o.mdx)("h3",{id:"community"},"Community"),(0,o.mdx)("p",null,"Ask questions on github or StackOverflow (Use the tag #fb-hydra):"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("a",{parentName:"li",href:"https://github.com/facebookresearch/hydra/discussions"},"github")),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("a",{parentName:"li",href:"https://stackoverflow.com/questions/tagged/fb-hydra"},"StackOverflow"))),(0,o.mdx)("p",null,"Follow Hydra on Twitter and Facebook:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("a",{parentName:"li",href:"https://www.facebook.com/Hydra-Framework-109364473802509/"},"Facebook page")),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("a",{parentName:"li",href:"https://twitter.com/Hydra_Framework"},"Twitter"))),(0,o.mdx)("h3",{id:"citing-hydra"},"Citing Hydra"),(0,o.mdx)("p",null,"If you use Hydra in your research please use the following BibTeX entry:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-text"},"@Misc{Yadan2019Hydra,\n author = {Omry Yadan},\n title = {Hydra - A framework for elegantly configuring complex applications},\n howpublished = {Github},\n year = {2019},\n url = {https://github.com/facebookresearch/hydra}\n}\n")))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/16568db6.fd66049a.js b/assets/js/16568db6.fd66049a.js deleted file mode 100644 index 50882e834e..0000000000 --- a/assets/js/16568db6.fd66049a.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[2175],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>d,MDXProvider:()=>u,mdx:()=>h,useMDXComponents:()=>p,withMDXComponents:()=>s});var a=n(96540);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var d=a.createContext({}),s=function(e){return function(t){var n=p(t.components);return a.createElement(e,o({},t,{components:n}))}},p=function(e){var t=a.useContext(d),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},u=function(e){var t=p(e.components);return a.createElement(d.Provider,{value:t},e.children)},c={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},f=a.forwardRef((function(e,t){var n=e.components,r=e.mdxType,o=e.originalType,l=e.parentName,d=m(e,["components","mdxType","originalType","parentName"]),s=p(n),u=r,f=s["".concat(l,".").concat(u)]||s[u]||c[u]||o;return n?a.createElement(f,i(i({ref:t},d),{},{components:n})):a.createElement(f,i({ref:t},d))}));function h(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var o=n.length,l=new Array(o);l[0]=f;var i={};for(var m in t)hasOwnProperty.call(t,m)&&(i[m]=t[m]);i.originalType=e,i.mdxType="string"==typeof e?e:r,l[1]=i;for(var d=2;d{n.r(t),n.d(t,{contentTitle:()=>m,default:()=>u,frontMatter:()=>i,metadata:()=>d,toc:()=>s});var a=n(58168),r=n(98587),o=(n(96540),n(15680)),l=(n(86025),n(75489),["components"]),i={id:"intro",title:"Getting started",sidebar_label:"Getting started"},m=void 0,d={unversionedId:"intro",id:"version-1.3/intro",title:"Getting started",description:"Introduction",source:"@site/versioned_docs/version-1.3/intro.md",sourceDirName:".",slug:"/intro",permalink:"/docs/1.3/intro",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/intro.md",tags:[],version:"1.3",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"intro",title:"Getting started",sidebar_label:"Getting started"},sidebar:"docs",next:{title:"Tutorials intro",permalink:"/docs/1.3/tutorials/intro"}},s=[{value:"Introduction",id:"introduction",children:[{value:"Key features:",id:"key-features",children:[],level:3}],level:2},{value:"Versions",id:"versions",children:[],level:2},{value:"Quick start guide",id:"quick-start-guide",children:[{value:"Installation",id:"installation",children:[],level:3},{value:"Basic example",id:"basic-example",children:[],level:3},{value:"Composition example",id:"composition-example",children:[],level:3},{value:"Multirun",id:"multirun",children:[],level:3}],level:2},{value:"Other stuff",id:"other-stuff",children:[{value:"Community",id:"community",children:[],level:3},{value:"Citing Hydra",id:"citing-hydra",children:[],level:3}],level:2}],p={toc:s};function u(e){var t=e.components,n=(0,r.A)(e,l);return(0,o.mdx)("wrapper",(0,a.A)({},p,n,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)("h2",{id:"introduction"},"Introduction"),(0,o.mdx)("p",null,"Hydra is an open-source Python framework that simplifies the development of research and other complex applications.\nThe key feature is the ability to dynamically create a hierarchical configuration by composition and override it through config files and the command line.\nThe name Hydra comes from its ability to run multiple similar jobs - much like a Hydra with multiple heads."),(0,o.mdx)("h3",{id:"key-features"},"Key features:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"Hierarchical configuration composable from multiple sources"),(0,o.mdx)("li",{parentName:"ul"},"Configuration can be specified or overridden from the command line"),(0,o.mdx)("li",{parentName:"ul"},"Dynamic command line tab completion"),(0,o.mdx)("li",{parentName:"ul"},"Run your application locally or launch it to run remotely"),(0,o.mdx)("li",{parentName:"ul"},"Run multiple jobs with different arguments with a single command")),(0,o.mdx)("h2",{id:"versions"},"Versions"),(0,o.mdx)("p",null,"Hydra supports Linux, Mac and Windows.",(0,o.mdx)("br",{parentName:"p"}),"\n","Use the version switcher in the top bar to switch between documentation versions."),(0,o.mdx)("table",null,(0,o.mdx)("thead",{parentName:"table"},(0,o.mdx)("tr",{parentName:"thead"},(0,o.mdx)("th",{parentName:"tr",align:null}),(0,o.mdx)("th",{parentName:"tr",align:null},"Version"),(0,o.mdx)("th",{parentName:"tr",align:null},"Release notes"),(0,o.mdx)("th",{parentName:"tr",align:null},"Python Versions"))),(0,o.mdx)("tbody",{parentName:"table"},(0,o.mdx)("tr",{parentName:"tbody"},(0,o.mdx)("td",{parentName:"tr",align:null},"\u25ba"),(0,o.mdx)("td",{parentName:"tr",align:null},"1.3 (Stable)"),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v1.3.0"},"Release notes")),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("strong",{parentName:"td"},"3.6 - 3.11"))),(0,o.mdx)("tr",{parentName:"tbody"},(0,o.mdx)("td",{parentName:"tr",align:null}),(0,o.mdx)("td",{parentName:"tr",align:null},"1.2"),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v1.2.0"},"Release notes")),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("strong",{parentName:"td"},"3.6 - 3.10"))),(0,o.mdx)("tr",{parentName:"tbody"},(0,o.mdx)("td",{parentName:"tr",align:null}),(0,o.mdx)("td",{parentName:"tr",align:null},"1.1"),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v1.1.1"},"Release notes")),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("strong",{parentName:"td"},"3.6 - 3.9"))),(0,o.mdx)("tr",{parentName:"tbody"},(0,o.mdx)("td",{parentName:"tr",align:null}),(0,o.mdx)("td",{parentName:"tr",align:null},"1.0"),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v1.0.7"},"Release notes")),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("strong",{parentName:"td"},"3.6 - 3.8"))),(0,o.mdx)("tr",{parentName:"tbody"},(0,o.mdx)("td",{parentName:"tr",align:null}),(0,o.mdx)("td",{parentName:"tr",align:null},"0.11"),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v0.11.3"},"Release notes")),(0,o.mdx)("td",{parentName:"tr",align:null},(0,o.mdx)("strong",{parentName:"td"},"2.7, 3.5 - 3.8"))))),(0,o.mdx)("h2",{id:"quick-start-guide"},"Quick start guide"),(0,o.mdx)("p",null,"This guide will show you some of the most important features you get by writing your application as a Hydra app.\nIf you only want to use Hydra for config composition, check out Hydra's ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.3/advanced/compose_api"},"compose API")," for an alternative.\nPlease also read the full ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.3/tutorials/basic/your_first_app/simple_cli"},"tutorial")," to gain a deeper understanding."),(0,o.mdx)("h3",{id:"installation"},"Installation"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-commandline"},"pip install hydra-core --upgrade\n")),(0,o.mdx)("h3",{id:"basic-example"},"Basic example"),(0,o.mdx)("p",null,"Config:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="conf/config.yaml"',title:'"conf/config.yaml"'},"db:\n driver: mysql\n user: omry\n pass: secret\n")),(0,o.mdx)("p",null,"Application:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'{4-6} title="my_app.py"',"{4-6}":!0,title:'"my_app.py"'},'import hydra\nfrom omegaconf import DictConfig, OmegaConf\n\n@hydra.main(version_base=None, config_path="conf", config_name="config")\ndef my_app(cfg : DictConfig) -> None:\n print(OmegaConf.to_yaml(cfg))\n\nif __name__ == "__main__":\n my_app()\n')),(0,o.mdx)("p",null,"You can learn more about OmegaConf ",(0,o.mdx)("a",{parentName:"p",href:"https://omegaconf.readthedocs.io/en/latest/usage.html#access-and-manipulation"},"here")," later."),(0,o.mdx)("p",null,(0,o.mdx)("inlineCode",{parentName:"p"},"config.yaml")," is loaded automatically when you run your application"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py\ndb:\n driver: mysql\n pass: secret\n user: omry\n")),(0,o.mdx)("p",null,"You can override values in the loaded config from the command line:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{4-5}","{4-5}":!0},"$ python my_app.py db.user=root db.pass=1234\ndb:\n driver: mysql\n user: root\n pass: 1234\n")),(0,o.mdx)("h3",{id:"composition-example"},"Composition example"),(0,o.mdx)("p",null,"You may want to alternate between two different databases. To support this create a ",(0,o.mdx)("inlineCode",{parentName:"p"},"config group")," named db,\nand place one config file for each alternative inside:\nThe directory structure of our application now looks like:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-text"},"\u251c\u2500\u2500 conf\n\u2502\xa0\xa0 \u251c\u2500\u2500 config.yaml\n\u2502\xa0\xa0 \u251c\u2500\u2500 db\n\u2502\xa0\xa0 \u2502\xa0\xa0 \u251c\u2500\u2500 mysql.yaml\n\u2502\xa0\xa0 \u2502\xa0\xa0 \u2514\u2500\u2500 postgresql.yaml\n\u2502\xa0\xa0 \u2514\u2500\u2500 __init__.py\n\u2514\u2500\u2500 my_app.py\n")),(0,o.mdx)("p",null,"Here is the new config:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="conf/config.yaml"',title:'"conf/config.yaml"'},"defaults:\n - db: mysql\n")),(0,o.mdx)("p",null,(0,o.mdx)("inlineCode",{parentName:"p"},"defaults")," is a special directive telling Hydra to use db/mysql.yaml when composing the configuration object.\nThe resulting cfg object is a composition of configs from defaults with configs specified in your ",(0,o.mdx)("inlineCode",{parentName:"p"},"config.yaml"),"."),(0,o.mdx)("p",null,"You can now choose which database configuration to use and override values from the command line: "),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py db=postgresql db.timeout=20\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 20\n user: postgres_user\n")),(0,o.mdx)("p",null,"You can have as many config groups as you need."),(0,o.mdx)("h3",{id:"multirun"},"Multirun"),(0,o.mdx)("p",null,"You can run your function multiple times with different configuration easily with the ",(0,o.mdx)("inlineCode",{parentName:"p"},"--multirun|-m")," flag."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre"},"$ python my_app.py --multirun db=mysql,postgresql\n[HYDRA] Sweep output dir : multirun/2020-01-09/01-16-29\n[HYDRA] Launching 2 jobs locally\n[HYDRA] #0 : db=mysql\ndb:\n driver: mysql\n pass: secret\n user: omry\n\n[HYDRA] #1 : db=postgresql\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 10\n user: postgres_user\n")),(0,o.mdx)("p",null,"There is a whole lot more to Hydra. Read the ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.3/tutorials/basic/your_first_app/simple_cli"},"tutorial")," to learn more."),(0,o.mdx)("h2",{id:"other-stuff"},"Other stuff"),(0,o.mdx)("h3",{id:"community"},"Community"),(0,o.mdx)("p",null,"Ask questions on github or StackOverflow (Use the tag #fb-hydra):"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("a",{parentName:"li",href:"https://github.com/facebookresearch/hydra/discussions"},"github")),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("a",{parentName:"li",href:"https://stackoverflow.com/questions/tagged/fb-hydra"},"StackOverflow"))),(0,o.mdx)("p",null,"Follow Hydra on Twitter and Facebook:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("a",{parentName:"li",href:"https://www.facebook.com/Hydra-Framework-109364473802509/"},"Facebook page")),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("a",{parentName:"li",href:"https://twitter.com/Hydra_Framework"},"Twitter"))),(0,o.mdx)("h3",{id:"citing-hydra"},"Citing Hydra"),(0,o.mdx)("p",null,"If you use Hydra in your research please use the following BibTeX entry:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-text"},"@Misc{Yadan2019Hydra,\n author = {Omry Yadan},\n title = {Hydra - A framework for elegantly configuring complex applications},\n howpublished = {Github},\n year = {2019},\n url = {https://github.com/facebookresearch/hydra}\n}\n")))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1760e2a5.3428e135.js b/assets/js/1760e2a5.3428e135.js deleted file mode 100644 index 7b99250bf7..0000000000 --- a/assets/js/1760e2a5.3428e135.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[1322],{15680:(e,n,r)=>{r.r(n),r.d(n,{MDXContext:()=>s,MDXProvider:()=>d,mdx:()=>h,useMDXComponents:()=>c,withMDXComponents:()=>u});var a=r(96540);function t(e,n,r){return n in e?Object.defineProperty(e,n,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[n]=r,e}function l(){return l=Object.assign||function(e){for(var n=1;n=0||(t[r]=e[r]);return t}(e,n);if(Object.getOwnPropertySymbols){var l=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(t[r]=e[r])}return t}var s=a.createContext({}),u=function(e){return function(n){var r=c(n.components);return a.createElement(e,l({},n,{components:r}))}},c=function(e){var n=a.useContext(s),r=n;return e&&(r="function"==typeof e?e(n):o(o({},n),e)),r},d=function(e){var n=c(e.components);return a.createElement(s.Provider,{value:n},e.children)},m={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},b=a.forwardRef((function(e,n){var r=e.components,t=e.mdxType,l=e.originalType,i=e.parentName,s=p(e,["components","mdxType","originalType","parentName"]),u=c(r),d=t,b=u["".concat(i,".").concat(d)]||u[d]||m[d]||l;return r?a.createElement(b,o(o({ref:n},s),{},{components:r})):a.createElement(b,o({ref:n},s))}));function h(e,n){var r=arguments,t=n&&n.mdxType;if("string"==typeof e||t){var l=r.length,i=new Array(l);i[0]=b;var o={};for(var p in n)hasOwnProperty.call(n,p)&&(o[p]=n[p]);o.originalType=e,o.mdxType="string"==typeof e?e:t,i[1]=o;for(var s=2;s{r.d(n,{A:()=>p,C:()=>s});var a=r(58168),t=r(96540),l=r(75489),i=r(44586),o=r(74098);function p(e){return t.createElement(l.default,(0,a.A)({},e,{to:(n=e.to,p=(0,o.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(r=null==p?void 0:p.name)?r:"current"]+n),target:"_blank"}));var n,r,p}function s(e){var n,r=null!=(n=e.text)?n:"Example (Click Here)";return t.createElement(p,e,t.createElement("span",null,"\xa0"),t.createElement("img",{src:"https://img.shields.io/badge/-"+r+"-informational",alt:"Example (Click Here)"}))}},39529:(e,n,r)=>{r.r(n),r.d(n,{contentTitle:()=>s,default:()=>m,frontMatter:()=>p,metadata:()=>u,toc:()=>c});var a=r(58168),t=r(98587),l=(r(96540),r(15680)),i=r(49595),o=["components"],p={id:"joblib_launcher",title:"Joblib Launcher plugin",sidebar_label:"Joblib Launcher plugin"},s=void 0,u={unversionedId:"plugins/joblib_launcher",id:"version-1.2/plugins/joblib_launcher",title:"Joblib Launcher plugin",description:"PyPI",source:"@site/versioned_docs/version-1.2/plugins/joblib_launcher.md",sourceDirName:"plugins",slug:"/plugins/joblib_launcher",permalink:"/docs/1.2/plugins/joblib_launcher",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/plugins/joblib_launcher.md",tags:[],version:"1.2",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"joblib_launcher",title:"Joblib Launcher plugin",sidebar_label:"Joblib Launcher plugin"},sidebar:"docs",previous:{title:"Colorlog plugin",permalink:"/docs/1.2/plugins/colorlog"},next:{title:"Ray Launcher plugin",permalink:"/docs/1.2/plugins/ray_launcher"}},c=[{value:"Installation",id:"installation",children:[],level:3},{value:"Usage",id:"usage",children:[],level:3}],d={toc:c};function m(e){var n=e.components,r=(0,t.A)(e,o);return(0,l.mdx)("wrapper",(0,a.A)({},d,r,{components:n,mdxType:"MDXLayout"}),(0,l.mdx)("p",null,(0,l.mdx)("a",{parentName:"p",href:"https://pypi.org/project/hydra-joblib-launcher/"},(0,l.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/v/hydra-joblib-launcher",alt:"PyPI"})),"\n",(0,l.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/l/hydra-joblib-launcher",alt:"PyPI - License"}),"\n",(0,l.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/pyversions/hydra-joblib-launcher",alt:"PyPI - Python Version"}),"\n",(0,l.mdx)("a",{parentName:"p",href:"https://pypistats.org/packages/hydra-joblib-launcher"},(0,l.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/dm/hydra-joblib-launcher.svg",alt:"PyPI - Downloads"})),(0,l.mdx)(i.C,{text:"Example application",to:"plugins/hydra_joblib_launcher/example",mdxType:"ExampleGithubLink"}),(0,l.mdx)(i.C,{text:"Plugin source",to:"plugins/hydra_joblib_launcher",mdxType:"ExampleGithubLink"})),(0,l.mdx)("p",null,"The Joblib Launcher plugin provides a launcher for parallel tasks based on ",(0,l.mdx)("a",{parentName:"p",href:"https://joblib.readthedocs.io/en/latest/parallel.html"},(0,l.mdx)("inlineCode",{parentName:"a"},"Joblib.Parallel")),"."),(0,l.mdx)("h3",{id:"installation"},"Installation"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"pip install hydra-joblib-launcher --upgrade\n")),(0,l.mdx)("h3",{id:"usage"},"Usage"),(0,l.mdx)("p",null,"Once installed, add ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra/launcher=joblib")," to your command line. Alternatively, override ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra/launcher")," in your config:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - override hydra/launcher: joblib\n")),(0,l.mdx)("p",null,"By default, process-based parallelism using all available CPU cores is used. By overriding the default configuration, it is e.g. possible limit the number of parallel executions."),(0,l.mdx)("p",null,"The JobLibLauncherConf backing the config is defined ",(0,l.mdx)(i.A,{to:"plugins/hydra_joblib_launcher/hydra_plugins/hydra_joblib_launcher/config.py",mdxType:"GithubLink"},"here"),":"),(0,l.mdx)("p",null,"You can discover the Joblib Launcher parameters with:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python your_app.py hydra/launcher=joblib --cfg hydra -p hydra.launcher"',title:'"$',python:!0,"your_app.py":!0,"hydra/launcher":"joblib","--cfg":!0,hydra:!0,"-p":!0,'hydra.launcher"':!0},"# @package hydra.launcher\n_target_: hydra_plugins.hydra_joblib_launcher.joblib_launcher.JoblibLauncher\nn_jobs: 10\nbackend: null\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")),(0,l.mdx)("p",null,"There are several standard approaches for configuring plugins. Check ",(0,l.mdx)("a",{parentName:"p",href:"/docs/1.2/patterns/configuring_plugins"},"this page")," for more information."),(0,l.mdx)("p",null,"See ",(0,l.mdx)("a",{parentName:"p",href:"https://joblib.readthedocs.io/en/latest/parallel.html"},(0,l.mdx)("inlineCode",{parentName:"a"},"Joblib.Parallel")," documentation")," for full details about the parameters above."),(0,l.mdx)("div",{class:"alert alert--info",role:"alert"},"NOTE: The only supported JobLib backend is Loky (process-based parallelism)."),(0,l.mdx)("br",null),(0,l.mdx)("p",null,"An ",(0,l.mdx)(i.A,{to:"plugins/hydra_joblib_launcher/example",mdxType:"GithubLink"},"example application")," using this launcher is provided in the plugin repository."),(0,l.mdx)("p",null,"Starting the app with ",(0,l.mdx)("inlineCode",{parentName:"p"},"python my_app.py --multirun task=1,2,3,4,5")," will launch five parallel executions:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-text"},"$ python my_app.py --multirun task=1,2,3,4,5\n[HYDRA] Joblib.Parallel(n_jobs=-1,verbose=0,timeout=None,pre_dispatch=2*n_jobs,batch_size=auto,temp_folder=None,max_nbytes=None,mmap_mode=r,backend=loky) 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")))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1760e2a5.d90bf87e.js b/assets/js/1760e2a5.d90bf87e.js new file mode 100644 index 0000000000..2878920873 --- /dev/null +++ b/assets/js/1760e2a5.d90bf87e.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[1322],{15680:(e,n,r)=>{r.r(n),r.d(n,{MDXContext:()=>s,MDXProvider:()=>d,mdx:()=>h,useMDXComponents:()=>c,withMDXComponents:()=>u});var a=r(96540);function t(e,n,r){return n in e?Object.defineProperty(e,n,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[n]=r,e}function l(){return l=Object.assign||function(e){for(var n=1;n=0||(t[r]=e[r]);return t}(e,n);if(Object.getOwnPropertySymbols){var l=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(t[r]=e[r])}return t}var s=a.createContext({}),u=function(e){return function(n){var r=c(n.components);return a.createElement(e,l({},n,{components:r}))}},c=function(e){var n=a.useContext(s),r=n;return e&&(r="function"==typeof e?e(n):o(o({},n),e)),r},d=function(e){var n=c(e.components);return a.createElement(s.Provider,{value:n},e.children)},m={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},b=a.forwardRef((function(e,n){var r=e.components,t=e.mdxType,l=e.originalType,i=e.parentName,s=p(e,["components","mdxType","originalType","parentName"]),u=c(r),d=t,b=u["".concat(i,".").concat(d)]||u[d]||m[d]||l;return r?a.createElement(b,o(o({ref:n},s),{},{components:r})):a.createElement(b,o({ref:n},s))}));function h(e,n){var r=arguments,t=n&&n.mdxType;if("string"==typeof e||t){var l=r.length,i=new Array(l);i[0]=b;var o={};for(var p in n)hasOwnProperty.call(n,p)&&(o[p]=n[p]);o.originalType=e,o.mdxType="string"==typeof e?e:t,i[1]=o;for(var s=2;s{r.d(n,{A:()=>p,C:()=>s});var a=r(58168),t=r(96540),l=r(75489),i=r(44586),o=r(74098);function p(e){return t.createElement(l.default,(0,a.A)({},e,{to:(n=e.to,p=(0,o.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(r=null==p?void 0:p.name)?r:"current"]+n),target:"_blank"}));var n,r,p}function s(e){var n,r=null!=(n=e.text)?n:"Example (Click Here)";return t.createElement(p,e,t.createElement("span",null,"\xa0"),t.createElement("img",{src:"https://img.shields.io/badge/-"+r+"-informational",alt:"Example (Click Here)"}))}},39529:(e,n,r)=>{r.r(n),r.d(n,{contentTitle:()=>s,default:()=>m,frontMatter:()=>p,metadata:()=>u,toc:()=>c});var a=r(58168),t=r(98587),l=(r(96540),r(15680)),i=r(49595),o=["components"],p={id:"joblib_launcher",title:"Joblib Launcher plugin",sidebar_label:"Joblib Launcher plugin"},s=void 0,u={unversionedId:"plugins/joblib_launcher",id:"version-1.2/plugins/joblib_launcher",title:"Joblib Launcher plugin",description:"PyPI",source:"@site/versioned_docs/version-1.2/plugins/joblib_launcher.md",sourceDirName:"plugins",slug:"/plugins/joblib_launcher",permalink:"/docs/1.2/plugins/joblib_launcher",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/plugins/joblib_launcher.md",tags:[],version:"1.2",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"joblib_launcher",title:"Joblib Launcher plugin",sidebar_label:"Joblib Launcher plugin"},sidebar:"docs",previous:{title:"Colorlog plugin",permalink:"/docs/1.2/plugins/colorlog"},next:{title:"Ray Launcher plugin",permalink:"/docs/1.2/plugins/ray_launcher"}},c=[{value:"Installation",id:"installation",children:[],level:3},{value:"Usage",id:"usage",children:[],level:3}],d={toc:c};function m(e){var n=e.components,r=(0,t.A)(e,o);return(0,l.mdx)("wrapper",(0,a.A)({},d,r,{components:n,mdxType:"MDXLayout"}),(0,l.mdx)("p",null,(0,l.mdx)("a",{parentName:"p",href:"https://pypi.org/project/hydra-joblib-launcher/"},(0,l.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/v/hydra-joblib-launcher",alt:"PyPI"})),"\n",(0,l.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/l/hydra-joblib-launcher",alt:"PyPI - License"}),"\n",(0,l.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/pyversions/hydra-joblib-launcher",alt:"PyPI - Python Version"}),"\n",(0,l.mdx)("a",{parentName:"p",href:"https://pypistats.org/packages/hydra-joblib-launcher"},(0,l.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/dm/hydra-joblib-launcher.svg",alt:"PyPI - Downloads"})),(0,l.mdx)(i.C,{text:"Example application",to:"plugins/hydra_joblib_launcher/example",mdxType:"ExampleGithubLink"}),(0,l.mdx)(i.C,{text:"Plugin source",to:"plugins/hydra_joblib_launcher",mdxType:"ExampleGithubLink"})),(0,l.mdx)("p",null,"The Joblib Launcher plugin provides a launcher for parallel tasks based on ",(0,l.mdx)("a",{parentName:"p",href:"https://joblib.readthedocs.io/en/latest/parallel.html"},(0,l.mdx)("inlineCode",{parentName:"a"},"Joblib.Parallel")),"."),(0,l.mdx)("h3",{id:"installation"},"Installation"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-commandline"},"pip install hydra-joblib-launcher --upgrade\n")),(0,l.mdx)("h3",{id:"usage"},"Usage"),(0,l.mdx)("p",null,"Once installed, add ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra/launcher=joblib")," to your command line. Alternatively, override ",(0,l.mdx)("inlineCode",{parentName:"p"},"hydra/launcher")," in your config:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - override hydra/launcher: joblib\n")),(0,l.mdx)("p",null,"By default, process-based parallelism using all available CPU cores is used. By overriding the default configuration, it is e.g. possible limit the number of parallel executions."),(0,l.mdx)("p",null,"The JobLibLauncherConf backing the config is defined ",(0,l.mdx)(i.A,{to:"plugins/hydra_joblib_launcher/hydra_plugins/hydra_joblib_launcher/config.py",mdxType:"GithubLink"},"here"),":"),(0,l.mdx)("p",null,"You can discover the Joblib Launcher parameters with:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python your_app.py hydra/launcher=joblib --cfg hydra -p hydra.launcher"',title:'"$',python:!0,"your_app.py":!0,"hydra/launcher":"joblib","--cfg":!0,hydra:!0,"-p":!0,'hydra.launcher"':!0},"# @package hydra.launcher\n_target_: hydra_plugins.hydra_joblib_launcher.joblib_launcher.JoblibLauncher\nn_jobs: 10\nbackend: null\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")),(0,l.mdx)("p",null,"There are several standard approaches for configuring plugins. Check ",(0,l.mdx)("a",{parentName:"p",href:"/docs/1.2/patterns/configuring_plugins"},"this page")," for more information."),(0,l.mdx)("p",null,"See ",(0,l.mdx)("a",{parentName:"p",href:"https://joblib.readthedocs.io/en/latest/parallel.html"},(0,l.mdx)("inlineCode",{parentName:"a"},"Joblib.Parallel")," documentation")," for full details about the parameters above."),(0,l.mdx)("div",{class:"alert alert--info",role:"alert"},"NOTE: The only supported JobLib backend is Loky (process-based parallelism)."),(0,l.mdx)("br",null),(0,l.mdx)("p",null,"An ",(0,l.mdx)(i.A,{to:"plugins/hydra_joblib_launcher/example",mdxType:"GithubLink"},"example application")," using this launcher is provided in the plugin repository."),(0,l.mdx)("p",null,"Starting the app with ",(0,l.mdx)("inlineCode",{parentName:"p"},"python my_app.py --multirun task=1,2,3,4,5")," will launch five parallel executions:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-text"},"$ python my_app.py --multirun task=1,2,3,4,5\n[HYDRA] Joblib.Parallel(n_jobs=-1,verbose=0,timeout=None,pre_dispatch=2*n_jobs,batch_size=auto,temp_folder=None,max_nbytes=None,mmap_mode=r,backend=loky) 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")))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/176287c7.1877abd6.js b/assets/js/176287c7.1877abd6.js deleted file mode 100644 index 7600586ebb..0000000000 --- a/assets/js/176287c7.1877abd6.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[4510],{15680:(e,t,r)=>{r.r(t),r.d(t,{MDXContext:()=>p,MDXProvider:()=>l,mdx:()=>f,useMDXComponents:()=>u,withMDXComponents:()=>d});var n=r(96540);function o(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(o[r]=e[r]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(o[r]=e[r])}return o}var p=n.createContext({}),d=function(e){return function(t){var r=u(t.components);return n.createElement(e,a({},t,{components:r}))}},u=function(e){var t=n.useContext(p),r=t;return e&&(r="function"==typeof e?e(t):c(c({},t),e)),r},l=function(e){var t=u(e.components);return n.createElement(p.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},y=n.forwardRef((function(e,t){var r=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,p=s(e,["components","mdxType","originalType","parentName"]),d=u(r),l=o,y=d["".concat(i,".").concat(l)]||d[l]||m[l]||a;return r?n.createElement(y,c(c({ref:t},p),{},{components:r})):n.createElement(y,c({ref:t},p))}));function f(e,t){var r=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=r.length,i=new Array(a);i[0]=y;var c={};for(var s in t)hasOwnProperty.call(t,s)&&(c[s]=t[s]);c.originalType=e,c.mdxType="string"==typeof e?e:o,i[1]=c;for(var p=2;p{r.r(t),r.d(t,{contentTitle:()=>s,default:()=>l,frontMatter:()=>c,metadata:()=>p,toc:()=>d});var n=r(58168),o=r(98587),a=(r(96540),r(15680)),i=["components"],c={id:"jupyter_notebooks",title:"Hydra in Jupyter Notebooks"},s=void 0,p={unversionedId:"advanced/jupyter_notebooks",id:"version-1.3/advanced/jupyter_notebooks",title:"Hydra in Jupyter Notebooks",description:"Hydra supports config composition inside Jupyter notebooks via the Compose API.",source:"@site/versioned_docs/version-1.3/advanced/jupyter_notebooks.md",sourceDirName:"advanced",slug:"/advanced/jupyter_notebooks",permalink:"/docs/1.3/advanced/jupyter_notebooks",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/advanced/jupyter_notebooks.md",tags:[],version:"1.3",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"jupyter_notebooks",title:"Hydra in Jupyter Notebooks"},sidebar:"docs",previous:{title:"Decorating the main function",permalink:"/docs/1.3/advanced/decorating_main"},next:{title:"Hydra in Unit Tests",permalink:"/docs/1.3/advanced/unit_testing"}},d=[],u={toc:d};function l(e){var t=e.components,r=(0,o.A)(e,i);return(0,a.mdx)("wrapper",(0,n.A)({},u,r,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)("p",null,"Hydra supports config composition inside Jupyter notebooks via the ",(0,a.mdx)("a",{parentName:"p",href:"/docs/1.3/advanced/compose_api"},"Compose API"),". "),(0,a.mdx)("p",null,"Run the Notebook in a the Binder to see a live demo, or open the Notebook source on GitHub."),(0,a.mdx)("p",null,(0,a.mdx)("a",{parentName:"p",href:"https://mybinder.org/v2/gh/facebookresearch/hydra/main?filepath=examples%252jupyter_notebooks"},(0,a.mdx)("img",{parentName:"a",src:"https://mybinder.org/badge_logo.svg",alt:"Binder"})),"\n",(0,a.mdx)("a",{parentName:"p",href:"https://github.com/facebookresearch/hydra//tree/main/examples/jupyter_notebooks/"},(0,a.mdx)("img",{parentName:"a",src:"https://img.shields.io/badge/-Notebooks%20source-informational",alt:"Notebook source"}))))}l.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/176287c7.424615e8.js b/assets/js/176287c7.424615e8.js new file mode 100644 index 0000000000..2e94926d9b --- /dev/null +++ b/assets/js/176287c7.424615e8.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[4510],{15680:(e,t,r)=>{r.r(t),r.d(t,{MDXContext:()=>c,MDXProvider:()=>l,mdx:()=>b,useMDXComponents:()=>u,withMDXComponents:()=>d});var n=r(96540);function o(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(o[r]=e[r]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(o[r]=e[r])}return o}var c=n.createContext({}),d=function(e){return function(t){var r=u(t.components);return n.createElement(e,a({},t,{components:r}))}},u=function(e){var t=n.useContext(c),r=t;return e&&(r="function"==typeof e?e(t):p(p({},t),e)),r},l=function(e){var t=u(e.components);return n.createElement(c.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},y=n.forwardRef((function(e,t){var r=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,c=s(e,["components","mdxType","originalType","parentName"]),d=u(r),l=o,y=d["".concat(i,".").concat(l)]||d[l]||m[l]||a;return r?n.createElement(y,p(p({ref:t},c),{},{components:r})):n.createElement(y,p({ref:t},c))}));function b(e,t){var r=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=r.length,i=new Array(a);i[0]=y;var p={};for(var s in t)hasOwnProperty.call(t,s)&&(p[s]=t[s]);p.originalType=e,p.mdxType="string"==typeof e?e:o,i[1]=p;for(var c=2;c{r.r(t),r.d(t,{contentTitle:()=>s,default:()=>l,frontMatter:()=>p,metadata:()=>c,toc:()=>d});var n=r(58168),o=r(98587),a=(r(96540),r(15680)),i=["components"],p={id:"jupyter_notebooks",title:"Hydra in Jupyter Notebooks"},s=void 0,c={unversionedId:"advanced/jupyter_notebooks",id:"version-1.3/advanced/jupyter_notebooks",title:"Hydra in Jupyter Notebooks",description:"Hydra supports config composition inside Jupyter notebooks via the Compose API.",source:"@site/versioned_docs/version-1.3/advanced/jupyter_notebooks.md",sourceDirName:"advanced",slug:"/advanced/jupyter_notebooks",permalink:"/docs/1.3/advanced/jupyter_notebooks",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/advanced/jupyter_notebooks.md",tags:[],version:"1.3",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"jupyter_notebooks",title:"Hydra in Jupyter Notebooks"},sidebar:"docs",previous:{title:"Decorating the main function",permalink:"/docs/1.3/advanced/decorating_main"},next:{title:"Hydra in Unit Tests",permalink:"/docs/1.3/advanced/unit_testing"}},d=[],u={toc:d};function l(e){var t=e.components,r=(0,o.A)(e,i);return(0,a.mdx)("wrapper",(0,n.A)({},u,r,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)("p",null,"Hydra supports config composition inside Jupyter notebooks via the ",(0,a.mdx)("a",{parentName:"p",href:"/docs/1.3/advanced/compose_api"},"Compose API"),". "),(0,a.mdx)("p",null,"Run the Notebook in a the Binder to see a live demo, or open the Notebook source on GitHub."),(0,a.mdx)("p",null,(0,a.mdx)("a",{parentName:"p",href:"https://mybinder.org/v2/gh/facebookresearch/hydra/main?filepath=examples%252jupyter_notebooks"},(0,a.mdx)("img",{parentName:"a",src:"https://mybinder.org/badge_logo.svg",alt:"Binder"})),"\n",(0,a.mdx)("a",{parentName:"p",href:"https://github.com/facebookresearch/hydra//tree/main/examples/jupyter_notebooks/"},(0,a.mdx)("img",{parentName:"a",src:"https://img.shields.io/badge/-Notebooks%20source-informational",alt:"Notebook source"}))))}l.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/17885660.8d55f4f5.js b/assets/js/17885660.8d55f4f5.js deleted file mode 100644 index fb4e7b1480..0000000000 --- a/assets/js/17885660.8d55f4f5.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[6432],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>d,MDXProvider:()=>p,mdx:()=>g,useMDXComponents:()=>c,withMDXComponents:()=>s});var a=t(96540);function i(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function o(){return o=Object.assign||function(e){for(var n=1;n=0||(i[t]=e[t]);return i}(e,n);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(i[t]=e[t])}return i}var d=a.createContext({}),s=function(e){return function(n){var t=c(n.components);return a.createElement(e,o({},n,{components:t}))}},c=function(e){var n=a.useContext(d),t=n;return e&&(t="function"==typeof e?e(n):r(r({},n),e)),t},p=function(e){var n=c(e.components);return a.createElement(d.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},h=a.forwardRef((function(e,n){var t=e.components,i=e.mdxType,o=e.originalType,l=e.parentName,d=m(e,["components","mdxType","originalType","parentName"]),s=c(t),p=i,h=s["".concat(l,".").concat(p)]||s[p]||u[p]||o;return t?a.createElement(h,r(r({ref:n},d),{},{components:t})):a.createElement(h,r({ref:n},d))}));function g(e,n){var t=arguments,i=n&&n.mdxType;if("string"==typeof e||i){var o=t.length,l=new Array(o);l[0]=h;var r={};for(var m in n)hasOwnProperty.call(n,m)&&(r[m]=n[m]);r.originalType=e,r.mdxType="string"==typeof e?e:i,l[1]=r;for(var d=2;d{t.r(n),t.d(n,{contentTitle:()=>m,default:()=>p,frontMatter:()=>r,metadata:()=>d,toc:()=>s});var a=t(58168),i=t(98587),o=(t(96540),t(15680)),l=["components"],r={id:"automatic_schema_matching",title:"Automatic schema-matching",hide_title:!0},m=void 0,d={unversionedId:"upgrades/1.0_to_1.1/automatic_schema_matching",id:"upgrades/1.0_to_1.1/automatic_schema_matching",title:"Automatic schema-matching",description:"In Hydra 1.0, when a config file is loaded, if a config with a matching name and group is present in the ConfigStore,",source:"@site/docs/upgrades/1.0_to_1.1/automatic_schema_matching.md",sourceDirName:"upgrades/1.0_to_1.1",slug:"/upgrades/1.0_to_1.1/automatic_schema_matching",permalink:"/docs/upgrades/1.0_to_1.1/automatic_schema_matching",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/upgrades/1.0_to_1.1/automatic_schema_matching.md",tags:[],version:"current",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"automatic_schema_matching",title:"Automatic schema-matching",hide_title:!0},sidebar:"docs",previous:{title:"Changes to Package Header",permalink:"/docs/upgrades/1.0_to_1.1/changes_to_package_header"},next:{title:"Config path changes",permalink:"/docs/upgrades/0.11_to_1.0/config_path_changes"}},s=[{value:"Migration",id:"migration",children:[{value:"Option 1: rename the Structured Config",id:"option-1-rename-the-structured-config",children:[{value:"Hydra 1.0",id:"hydra-10",children:[],level:4},{value:"Hydra 1.1",id:"hydra-11",children:[],level:4}],level:3},{value:"Option 2: rename the config file",id:"option-2-rename-the-config-file",children:[{value:"Hydra 1.0",id:"hydra-10-1",children:[],level:4},{value:"Hydra 1.1",id:"hydra-11-1",children:[],level:4}],level:3}],level:2}],c={toc:s};function p(e){var n=e.components,t=(0,i.A)(e,l);return(0,o.mdx)("wrapper",(0,a.A)({},c,t,{components:n,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"In Hydra 1.0, when a config file is loaded, if a config with a matching name and group is present in the ",(0,o.mdx)("inlineCode",{parentName:"p"},"ConfigStore"),",\nit is used as the schema for the newly loaded config."),(0,o.mdx)("p",null,"There are several problems with this approach:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("strong",{parentName:"li"},"Inflexible"),": This approach can only be used when a schema should validate a single config file.\nIt does not work if you want to use the same schema to validate multiple config files."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("strong",{parentName:"li"},"Unexpected"),": This behavior can be unexpected. There is no way to tell this is going to happen when looking at a given\nconfig file.")),(0,o.mdx)("p",null,"Hydra 1.1 deprecates this behavior in favor of an explicit config extension via the Defaults List.",(0,o.mdx)("br",{parentName:"p"}),"\n","This upgrade page aims to provide a summary of the required changes. It is highly recommended that you read the following pages:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("a",{parentName:"li",href:"/docs/advanced/defaults_list"},"Background: The Defaults List")),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("a",{parentName:"li",href:"/docs/patterns/extending_configs"},"Background: Extending configs")),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("a",{parentName:"li",href:"/docs/tutorials/structured_config/schema"},"Tutorial: Structured config schema"))),(0,o.mdx)("h2",{id:"migration"},"Migration"),(0,o.mdx)("p",null,"Before the upgrade, you have two different configs with the same name (a config file, and a Structured Config in the ",(0,o.mdx)("inlineCode",{parentName:"p"},"ConfigStore"),").\nYou need to rename one of them. Depending on the circumstances and your preference you may rename one or the other."),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"If you control both configs, you can rename either of them."),(0,o.mdx)("li",{parentName:"ul"},"If you only control the config file, rename it.")),(0,o.mdx)("h3",{id:"option-1-rename-the-structured-config"},"Option 1: rename the Structured Config"),(0,o.mdx)("p",null,"This option is less disruptive. Use it if you control the Structured Config. "),(0,o.mdx)("ol",null,(0,o.mdx)("li",{parentName:"ol"},"Use a different name when storing the schema into the Config Store. Common choices:",(0,o.mdx)("ul",{parentName:"li"},(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"base_")," prefix, e.g. ",(0,o.mdx)("inlineCode",{parentName:"li"},"base_mysql"),"."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"_schema")," suffix, e.g. ",(0,o.mdx)("inlineCode",{parentName:"li"},"mysql_schema"),"."))),(0,o.mdx)("li",{parentName:"ol"},"Add the schema to the Defaults List of the extending config file.")),(0,o.mdx)("details",null,(0,o.mdx)("summary",null,"Click to show an example"),(0,o.mdx)("h4",{id:"hydra-10"},"Hydra 1.0"),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml"',title:'"db/mysql.yaml"'},"# @package _group_\nhost: localhost\nport: 3306\n\n\n\n\n\n\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="db/mysql schema in the ConfigStore"',title:'"db/mysql',schema:!0,in:!0,the:!0,'ConfigStore"':!0},'@dataclass\nclass MySQLConfig:\n host: str\n port: int\n\ncs = ConfigStore.instance()\ncs.store(group="db",\n name="mysql", \n node=MySQLConfig)\n')))),(0,o.mdx)("h4",{id:"hydra-11"},"Hydra 1.1"),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml" {1,2}',title:'"db/mysql.yaml"',"{1,2}":!0},"defaults:\n - base_mysql\n\nhost: localhost\nport: 3306\n\n\n\n\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="db/mysql schema in the ConfigStore" {8}',title:'"db/mysql',schema:!0,in:!0,the:!0,'ConfigStore"':!0,"{8}":!0},'@dataclass\nclass MySQLConfig:\n host: str\n port: int\n\ncs = ConfigStore.instance()\ncs.store(group="db",\n name="base_mysql", \n node=MySQLConfig)\n'))))),(0,o.mdx)("h3",{id:"option-2-rename-the-config-file"},"Option 2: rename the config file"),(0,o.mdx)("p",null,"This option is a bit more disruptive. Use it if you only control the config file."),(0,o.mdx)("ol",null,(0,o.mdx)("li",{parentName:"ol"},"Rename the config file. Common choices are ",(0,o.mdx)("inlineCode",{parentName:"li"},"custom_")," or ",(0,o.mdx)("inlineCode",{parentName:"li"},"my_")," prefix, e.g. ",(0,o.mdx)("inlineCode",{parentName:"li"},"custom_mysql.yaml"),". You can also use a domain specific name like ",(0,o.mdx)("inlineCode",{parentName:"li"},"prod_mysql.yaml"),"."),(0,o.mdx)("li",{parentName:"ol"},"Add the schema to the Defaults List of the extending config file."),(0,o.mdx)("li",{parentName:"ol"},"Update references to the config name accordingly, e.g. on the command-line ",(0,o.mdx)("inlineCode",{parentName:"li"},"db=mysql")," would become ",(0,o.mdx)("inlineCode",{parentName:"li"},"db=custom_mysql"),", and in a defaults list ",(0,o.mdx)("inlineCode",{parentName:"li"},"db: mysql")," would become ",(0,o.mdx)("inlineCode",{parentName:"li"},"db: custom_mysql"),".")),(0,o.mdx)("details",null,(0,o.mdx)("summary",null,"Click to show an example"),(0,o.mdx)("h4",{id:"hydra-10-1"},"Hydra 1.0"),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml"',title:'"db/mysql.yaml"'},"# @package _group_\nhost: localhost\nport: 3306\n")),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - db: mysql\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="db/mysql schema in the ConfigStore"',title:'"db/mysql',schema:!0,in:!0,the:!0,'ConfigStore"':!0},'@dataclass\nclass MySQLConfig:\n host: str\n port: int\n\ncs = ConfigStore.instance()\ncs.store(group="db",\n name="mysql", \n node=MySQLConfig)\n\n')))),(0,o.mdx)("h4",{id:"hydra-11-1"},"Hydra 1.1"),(0,o.mdx)("p",null,"Rename ",(0,o.mdx)("inlineCode",{parentName:"p"},"db/mysql.yaml")," to ",(0,o.mdx)("inlineCode",{parentName:"p"},"db/custom_mysql.yaml")," and explicitly add the schema to the Defaults List."),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/custom_mysql.yaml" {1,2}',title:'"db/custom_mysql.yaml"',"{1,2}":!0},"defaults:\n - mysql\n\nhost: localhost\nport: 3306\n")),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {2}',title:'"config.yaml"',"{2}":!0},"defaults:\n - db: custom_mysql\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="db/mysql schema in the ConfigStore"',title:'"db/mysql',schema:!0,in:!0,the:!0,'ConfigStore"':!0},"\n\n\n\n\n NO CHANGES\n\n\n\n\n\n\n")))),(0,o.mdx)("p",null,"Don't forget to also update your command line overrides from ",(0,o.mdx)("inlineCode",{parentName:"p"},"db=mysql")," to ",(0,o.mdx)("inlineCode",{parentName:"p"},"db=custom_mysql"),".")))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/17885660.8ed6bb7b.js b/assets/js/17885660.8ed6bb7b.js new file mode 100644 index 0000000000..0bff5fa9b3 --- /dev/null +++ b/assets/js/17885660.8ed6bb7b.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[6432],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>d,MDXProvider:()=>p,mdx:()=>g,useMDXComponents:()=>c,withMDXComponents:()=>s});var a=t(96540);function i(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function o(){return o=Object.assign||function(e){for(var n=1;n=0||(i[t]=e[t]);return i}(e,n);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(i[t]=e[t])}return i}var d=a.createContext({}),s=function(e){return function(n){var t=c(n.components);return a.createElement(e,o({},n,{components:t}))}},c=function(e){var n=a.useContext(d),t=n;return e&&(t="function"==typeof e?e(n):r(r({},n),e)),t},p=function(e){var n=c(e.components);return a.createElement(d.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},h=a.forwardRef((function(e,n){var t=e.components,i=e.mdxType,o=e.originalType,l=e.parentName,d=m(e,["components","mdxType","originalType","parentName"]),s=c(t),p=i,h=s["".concat(l,".").concat(p)]||s[p]||u[p]||o;return t?a.createElement(h,r(r({ref:n},d),{},{components:t})):a.createElement(h,r({ref:n},d))}));function g(e,n){var t=arguments,i=n&&n.mdxType;if("string"==typeof e||i){var o=t.length,l=new Array(o);l[0]=h;var r={};for(var m in n)hasOwnProperty.call(n,m)&&(r[m]=n[m]);r.originalType=e,r.mdxType="string"==typeof e?e:i,l[1]=r;for(var d=2;d{t.r(n),t.d(n,{contentTitle:()=>m,default:()=>p,frontMatter:()=>r,metadata:()=>d,toc:()=>s});var a=t(58168),i=t(98587),o=(t(96540),t(15680)),l=["components"],r={id:"automatic_schema_matching",title:"Automatic schema-matching",hide_title:!0},m=void 0,d={unversionedId:"upgrades/1.0_to_1.1/automatic_schema_matching",id:"upgrades/1.0_to_1.1/automatic_schema_matching",title:"Automatic schema-matching",description:"In Hydra 1.0, when a config file is loaded, if a config with a matching name and group is present in the ConfigStore,",source:"@site/docs/upgrades/1.0_to_1.1/automatic_schema_matching.md",sourceDirName:"upgrades/1.0_to_1.1",slug:"/upgrades/1.0_to_1.1/automatic_schema_matching",permalink:"/docs/upgrades/1.0_to_1.1/automatic_schema_matching",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/upgrades/1.0_to_1.1/automatic_schema_matching.md",tags:[],version:"current",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"automatic_schema_matching",title:"Automatic schema-matching",hide_title:!0},sidebar:"docs",previous:{title:"Changes to Package Header",permalink:"/docs/upgrades/1.0_to_1.1/changes_to_package_header"},next:{title:"Config path changes",permalink:"/docs/upgrades/0.11_to_1.0/config_path_changes"}},s=[{value:"Migration",id:"migration",children:[{value:"Option 1: rename the Structured Config",id:"option-1-rename-the-structured-config",children:[{value:"Hydra 1.0",id:"hydra-10",children:[],level:4},{value:"Hydra 1.1",id:"hydra-11",children:[],level:4}],level:3},{value:"Option 2: rename the config file",id:"option-2-rename-the-config-file",children:[{value:"Hydra 1.0",id:"hydra-10-1",children:[],level:4},{value:"Hydra 1.1",id:"hydra-11-1",children:[],level:4}],level:3}],level:2}],c={toc:s};function p(e){var n=e.components,t=(0,i.A)(e,l);return(0,o.mdx)("wrapper",(0,a.A)({},c,t,{components:n,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"In Hydra 1.0, when a config file is loaded, if a config with a matching name and group is present in the ",(0,o.mdx)("inlineCode",{parentName:"p"},"ConfigStore"),",\nit is used as the schema for the newly loaded config."),(0,o.mdx)("p",null,"There are several problems with this approach:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("strong",{parentName:"li"},"Inflexible"),": This approach can only be used when a schema should validate a single config file.\nIt does not work if you want to use the same schema to validate multiple config files."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("strong",{parentName:"li"},"Unexpected"),": This behavior can be unexpected. There is no way to tell this is going to happen when looking at a given\nconfig file.")),(0,o.mdx)("p",null,"Hydra 1.1 deprecates this behavior in favor of an explicit config extension via the Defaults List.",(0,o.mdx)("br",{parentName:"p"}),"\n","This upgrade page aims to provide a summary of the required changes. It is highly recommended that you read the following pages:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("a",{parentName:"li",href:"/docs/advanced/defaults_list"},"Background: The Defaults List")),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("a",{parentName:"li",href:"/docs/patterns/extending_configs"},"Background: Extending configs")),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("a",{parentName:"li",href:"/docs/tutorials/structured_config/schema"},"Tutorial: Structured config schema"))),(0,o.mdx)("h2",{id:"migration"},"Migration"),(0,o.mdx)("p",null,"Before the upgrade, you have two different configs with the same name (a config file, and a Structured Config in the ",(0,o.mdx)("inlineCode",{parentName:"p"},"ConfigStore"),").\nYou need to rename one of them. Depending on the circumstances and your preference you may rename one or the other."),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"If you control both configs, you can rename either of them."),(0,o.mdx)("li",{parentName:"ul"},"If you only control the config file, rename it.")),(0,o.mdx)("h3",{id:"option-1-rename-the-structured-config"},"Option 1: rename the Structured Config"),(0,o.mdx)("p",null,"This option is less disruptive. Use it if you control the Structured Config. "),(0,o.mdx)("ol",null,(0,o.mdx)("li",{parentName:"ol"},"Use a different name when storing the schema into the Config Store. Common choices:",(0,o.mdx)("ul",{parentName:"li"},(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"base_")," prefix, e.g. ",(0,o.mdx)("inlineCode",{parentName:"li"},"base_mysql"),"."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"_schema")," suffix, e.g. ",(0,o.mdx)("inlineCode",{parentName:"li"},"mysql_schema"),"."))),(0,o.mdx)("li",{parentName:"ol"},"Add the schema to the Defaults List of the extending config file.")),(0,o.mdx)("details",null,(0,o.mdx)("summary",null,"Click to show an example"),(0,o.mdx)("h4",{id:"hydra-10"},"Hydra 1.0"),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml"',title:'"db/mysql.yaml"'},"# @package _group_\nhost: localhost\nport: 3306\n\n\n\n\n\n\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="db/mysql schema in the ConfigStore"',title:'"db/mysql',schema:!0,in:!0,the:!0,'ConfigStore"':!0},'@dataclass\nclass MySQLConfig:\n host: str\n port: int\n\ncs = ConfigStore.instance()\ncs.store(group="db",\n name="mysql", \n node=MySQLConfig)\n')))),(0,o.mdx)("h4",{id:"hydra-11"},"Hydra 1.1"),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml" {1,2}',title:'"db/mysql.yaml"',"{1,2}":!0},"defaults:\n - base_mysql\n\nhost: localhost\nport: 3306\n\n\n\n\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="db/mysql schema in the ConfigStore" {8}',title:'"db/mysql',schema:!0,in:!0,the:!0,'ConfigStore"':!0,"{8}":!0},'@dataclass\nclass MySQLConfig:\n host: str\n port: int\n\ncs = ConfigStore.instance()\ncs.store(group="db",\n name="base_mysql", \n node=MySQLConfig)\n'))))),(0,o.mdx)("h3",{id:"option-2-rename-the-config-file"},"Option 2: rename the config file"),(0,o.mdx)("p",null,"This option is a bit more disruptive. Use it if you only control the config file."),(0,o.mdx)("ol",null,(0,o.mdx)("li",{parentName:"ol"},"Rename the config file. Common choices are ",(0,o.mdx)("inlineCode",{parentName:"li"},"custom_")," or ",(0,o.mdx)("inlineCode",{parentName:"li"},"my_")," prefix, e.g. ",(0,o.mdx)("inlineCode",{parentName:"li"},"custom_mysql.yaml"),". You can also use a domain specific name like ",(0,o.mdx)("inlineCode",{parentName:"li"},"prod_mysql.yaml"),"."),(0,o.mdx)("li",{parentName:"ol"},"Add the schema to the Defaults List of the extending config file."),(0,o.mdx)("li",{parentName:"ol"},"Update references to the config name accordingly, e.g. on the command-line ",(0,o.mdx)("inlineCode",{parentName:"li"},"db=mysql")," would become ",(0,o.mdx)("inlineCode",{parentName:"li"},"db=custom_mysql"),", and in a defaults list ",(0,o.mdx)("inlineCode",{parentName:"li"},"db: mysql")," would become ",(0,o.mdx)("inlineCode",{parentName:"li"},"db: custom_mysql"),".")),(0,o.mdx)("details",null,(0,o.mdx)("summary",null,"Click to show an example"),(0,o.mdx)("h4",{id:"hydra-10-1"},"Hydra 1.0"),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml"',title:'"db/mysql.yaml"'},"# @package _group_\nhost: localhost\nport: 3306\n")),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - db: mysql\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="db/mysql schema in the ConfigStore"',title:'"db/mysql',schema:!0,in:!0,the:!0,'ConfigStore"':!0},'@dataclass\nclass MySQLConfig:\n host: str\n port: int\n\ncs = ConfigStore.instance()\ncs.store(group="db",\n name="mysql", \n node=MySQLConfig)\n\n')))),(0,o.mdx)("h4",{id:"hydra-11-1"},"Hydra 1.1"),(0,o.mdx)("p",null,"Rename ",(0,o.mdx)("inlineCode",{parentName:"p"},"db/mysql.yaml")," to ",(0,o.mdx)("inlineCode",{parentName:"p"},"db/custom_mysql.yaml")," and explicitly add the schema to the Defaults List."),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/custom_mysql.yaml" {1,2}',title:'"db/custom_mysql.yaml"',"{1,2}":!0},"defaults:\n - mysql\n\nhost: localhost\nport: 3306\n")),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {2}',title:'"config.yaml"',"{2}":!0},"defaults:\n - db: custom_mysql\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="db/mysql schema in the ConfigStore"',title:'"db/mysql',schema:!0,in:!0,the:!0,'ConfigStore"':!0},"\n\n\n\n\n NO CHANGES\n\n\n\n\n\n\n")))),(0,o.mdx)("p",null,"Don't forget to also update your command line overrides from ",(0,o.mdx)("inlineCode",{parentName:"p"},"db=mysql")," to ",(0,o.mdx)("inlineCode",{parentName:"p"},"db=custom_mysql"),".")))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/17b1a13a.74377c20.js b/assets/js/17b1a13a.74377c20.js deleted file mode 100644 index 2341a4377a..0000000000 --- a/assets/js/17b1a13a.74377c20.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[6582],{15680:(e,t,r)=>{r.r(t),r.d(t,{MDXContext:()=>l,MDXProvider:()=>f,mdx:()=>m,useMDXComponents:()=>u,withMDXComponents:()=>p});var n=r(96540);function o(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function i(){return i=Object.assign||function(e){for(var t=1;t=0||(o[r]=e[r]);return o}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(o[r]=e[r])}return o}var l=n.createContext({}),p=function(e){return function(t){var r=u(t.components);return n.createElement(e,i({},t,{components:r}))}},u=function(e){var t=n.useContext(l),r=t;return e&&(r="function"==typeof e?e(t):c(c({},t),e)),r},f=function(e){var t=u(e.components);return n.createElement(l.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},b=n.forwardRef((function(e,t){var r=e.components,o=e.mdxType,i=e.originalType,a=e.parentName,l=s(e,["components","mdxType","originalType","parentName"]),p=u(r),f=o,b=p["".concat(a,".").concat(f)]||p[f]||d[f]||i;return r?n.createElement(b,c(c({ref:t},l),{},{components:r})):n.createElement(b,c({ref:t},l))}));function m(e,t){var r=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var i=r.length,a=new Array(i);a[0]=b;var c={};for(var s in t)hasOwnProperty.call(t,s)&&(c[s]=t[s]);c.originalType=e,c.mdxType="string"==typeof e?e:o,a[1]=c;for(var l=2;l{r.r(t),r.d(t,{contentTitle:()=>s,default:()=>f,frontMatter:()=>c,metadata:()=>l,toc:()=>p});var n=r(58168),o=r(98587),i=(r(96540),r(15680)),a=["components"],c={id:"intro",title:"Introduction",sidebar_label:"Introduction"},s=void 0,l={unversionedId:"fb/intro",id:"version-0.11/fb/intro",title:"Introduction",description:"Facebook specific docs are only available in version 1.0 and newer. Please switch version from the version link at the top bar.",source:"@site/versioned_docs/version-0.11/fb/intro.md",sourceDirName:"fb",slug:"/fb/intro",permalink:"/docs/0.11/fb/intro",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-0.11/fb/intro.md",tags:[],version:"0.11",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"intro",title:"Introduction",sidebar_label:"Introduction"}},p=[],u={toc:p};function f(e){var t=e.components,r=(0,o.A)(e,a);return(0,i.mdx)("wrapper",(0,n.A)({},u,r,{components:t,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Facebook specific docs are only available in version 1.0 and newer. Please switch version from the version link at the top bar."))}f.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/17b1a13a.7d5fa80a.js b/assets/js/17b1a13a.7d5fa80a.js new file mode 100644 index 0000000000..e9c912d5b9 --- /dev/null +++ b/assets/js/17b1a13a.7d5fa80a.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[6582],{15680:(e,t,r)=>{r.r(t),r.d(t,{MDXContext:()=>l,MDXProvider:()=>f,mdx:()=>m,useMDXComponents:()=>u,withMDXComponents:()=>p});var n=r(96540);function o(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function i(){return i=Object.assign||function(e){for(var t=1;t=0||(o[r]=e[r]);return o}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(o[r]=e[r])}return o}var l=n.createContext({}),p=function(e){return function(t){var r=u(t.components);return n.createElement(e,i({},t,{components:r}))}},u=function(e){var t=n.useContext(l),r=t;return e&&(r="function"==typeof e?e(t):c(c({},t),e)),r},f=function(e){var t=u(e.components);return n.createElement(l.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},b=n.forwardRef((function(e,t){var r=e.components,o=e.mdxType,i=e.originalType,a=e.parentName,l=s(e,["components","mdxType","originalType","parentName"]),p=u(r),f=o,b=p["".concat(a,".").concat(f)]||p[f]||d[f]||i;return r?n.createElement(b,c(c({ref:t},l),{},{components:r})):n.createElement(b,c({ref:t},l))}));function m(e,t){var r=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var i=r.length,a=new Array(i);a[0]=b;var c={};for(var s in t)hasOwnProperty.call(t,s)&&(c[s]=t[s]);c.originalType=e,c.mdxType="string"==typeof e?e:o,a[1]=c;for(var l=2;l{r.r(t),r.d(t,{contentTitle:()=>s,default:()=>f,frontMatter:()=>c,metadata:()=>l,toc:()=>p});var n=r(58168),o=r(98587),i=(r(96540),r(15680)),a=["components"],c={id:"intro",title:"Introduction",sidebar_label:"Introduction"},s=void 0,l={unversionedId:"fb/intro",id:"version-0.11/fb/intro",title:"Introduction",description:"Facebook specific docs are only available in version 1.0 and newer. Please switch version from the version link at the top bar.",source:"@site/versioned_docs/version-0.11/fb/intro.md",sourceDirName:"fb",slug:"/fb/intro",permalink:"/docs/0.11/fb/intro",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-0.11/fb/intro.md",tags:[],version:"0.11",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"intro",title:"Introduction",sidebar_label:"Introduction"}},p=[],u={toc:p};function f(e){var t=e.components,r=(0,o.A)(e,a);return(0,i.mdx)("wrapper",(0,n.A)({},u,r,{components:t,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Facebook specific docs are only available in version 1.0 and newer. Please switch version from the version link at the top bar."))}f.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/17e73f1c.079bda0a.js b/assets/js/17e73f1c.079bda0a.js deleted file mode 100644 index 0b86aef45e..0000000000 --- a/assets/js/17e73f1c.079bda0a.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[7088],{15680:(e,n,r)=>{r.r(n),r.d(n,{MDXContext:()=>s,MDXProvider:()=>u,mdx:()=>f,useMDXComponents:()=>d,withMDXComponents:()=>c});var t=r(96540);function o(e,n,r){return n in e?Object.defineProperty(e,n,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[n]=r,e}function a(){return a=Object.assign||function(e){for(var n=1;n=0||(o[r]=e[r]);return o}(e,n);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(o[r]=e[r])}return o}var s=t.createContext({}),c=function(e){return function(n){var r=d(n.components);return t.createElement(e,a({},n,{components:r}))}},d=function(e){var n=t.useContext(s),r=n;return e&&(r="function"==typeof e?e(n):p(p({},n),e)),r},u=function(e){var n=d(e.components);return t.createElement(s.Provider,{value:n},e.children)},m={inlineCode:"code",wrapper:function(e){var n=e.children;return t.createElement(t.Fragment,{},n)}},h=t.forwardRef((function(e,n){var r=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,s=l(e,["components","mdxType","originalType","parentName"]),c=d(r),u=o,h=c["".concat(i,".").concat(u)]||c[u]||m[u]||a;return r?t.createElement(h,p(p({ref:n},s),{},{components:r})):t.createElement(h,p({ref:n},s))}));function f(e,n){var r=arguments,o=n&&n.mdxType;if("string"==typeof e||o){var a=r.length,i=new Array(a);i[0]=h;var p={};for(var l in n)hasOwnProperty.call(n,l)&&(p[l]=n[l]);p.originalType=e,p.mdxType="string"==typeof e?e:o,i[1]=p;for(var s=2;s{r.d(n,{A:()=>l,C:()=>s});var t=r(58168),o=r(96540),a=r(75489),i=r(44586),p=r(74098);function l(e){return o.createElement(a.default,(0,t.A)({},e,{to:(n=e.to,l=(0,p.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(r=null==l?void 0:l.name)?r:"current"]+n),target:"_blank"}));var n,r,l}function s(e){var n,r=null!=(n=e.text)?n:"Example (Click Here)";return o.createElement(l,e,o.createElement("span",null,"\xa0"),o.createElement("img",{src:"https://img.shields.io/badge/-"+r+"-informational",alt:"Example (Click Here)"}))}},43395:(e,n,r)=>{r.r(n),r.d(n,{contentTitle:()=>s,default:()=>m,frontMatter:()=>l,metadata:()=>c,toc:()=>d});var t=r(58168),o=r(98587),a=(r(96540),r(15680)),i=r(49595),p=["components"],l={id:"app_help",title:"Customizing Application's help",sidebar_label:"Customizing Application's help"},s=void 0,c={unversionedId:"configure_hydra/app_help",id:"version-1.3/configure_hydra/app_help",title:"Customizing Application's help",description:"Hydra provides two different help options:",source:"@site/versioned_docs/version-1.3/configure_hydra/app_help.md",sourceDirName:"configure_hydra",slug:"/configure_hydra/app_help",permalink:"/docs/1.3/configure_hydra/app_help",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/configure_hydra/app_help.md",tags:[],version:"1.3",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"app_help",title:"Customizing Application's help",sidebar_label:"Customizing Application's help"},sidebar:"docs",previous:{title:"Customizing working directory pattern",permalink:"/docs/1.3/configure_hydra/workdir"},next:{title:"Colorlog plugin",permalink:"/docs/1.3/plugins/colorlog"}},d=[],u={toc:d};function m(e){var n=e.components,r=(0,o.A)(e,p);return(0,a.mdx)("wrapper",(0,t.A)({},u,r,{components:n,mdxType:"MDXLayout"}),(0,a.mdx)(i.C,{text:"Example application",to:"examples/configure_hydra/custom_help",mdxType:"ExampleGithubLink"}),(0,a.mdx)("p",null,"Hydra provides two different help options:"),(0,a.mdx)("ul",null,(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"--help")," : Application specific help"),(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"--hydra-help")," Hydra specific help. ")),(0,a.mdx)("p",null,"Example output of ",(0,a.mdx)("inlineCode",{parentName:"p"},"--help"),":"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text"},"$ python my_app.py --help\n== AwesomeApp ==\n\nThis is AwesomeApp!\nYou can choose a db driver by appending\n== Configuration groups ==\nCompose your configuration from those groups (db=mysql)\n\ndb: mysql, postgresql\n\n\n== Config ==\nThis is the config generated for this run.\nYou can override everything, for example:\npython my_app.py db.user=foo db.pass=bar\n-------\ndb:\n driver: mysql\n user: omry\n pass: secret\n\n-------\n\nPowered by Hydra (https://hydra.cc)\nUse --hydra-help to view Hydra specific help\n")),(0,a.mdx)("p",null,"This output is generated from the following config group option (selected in ",(0,a.mdx)("inlineCode",{parentName:"p"},"config.yaml")," to be used by default): "),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="hydra/help/my_app_help.yaml"',title:'"hydra/help/my_app_help.yaml"'},"# App name, override to match the name your app is known by\napp_name: AwesomeApp\n\n# Help header, customize to describe your app to your users\nheader: == ${hydra.help.app_name} ==\n\nfooter: |-\n Powered by Hydra (https://hydra.cc)\n Use --hydra-help to view Hydra specific help\n\n# Basic Hydra flags:\n# $FLAGS_HELP\n#\n# Config groups, choose one of:\n# $APP_CONFIG_GROUPS: All config groups that does not start with hydra/.\n# $HYDRA_CONFIG_GROUPS: All the Hydra config groups (starts with hydra/)\n#\n# Configuration generated with overrides:\n# $CONFIG : Generated config\n#\ntemplate: |-\n ${hydra.help.header}\n\n This is ${hydra.help.app_name}!\n You can choose a db driver by appending\n == Configuration groups ==\n Compose your configuration from those groups (db=mysql)\n\n $APP_CONFIG_GROUPS\n\n == Config ==\n This is the config generated for this run.\n You can override everything, for example:\n python my_app.py db.user=foo db.pass=bar\n -------\n $CONFIG\n -------\n \n ${hydra.help.footer}\n")))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/17e73f1c.09806eaf.js b/assets/js/17e73f1c.09806eaf.js new file mode 100644 index 0000000000..d516ef6617 --- /dev/null +++ b/assets/js/17e73f1c.09806eaf.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[7088],{15680:(e,n,r)=>{r.r(n),r.d(n,{MDXContext:()=>s,MDXProvider:()=>u,mdx:()=>f,useMDXComponents:()=>d,withMDXComponents:()=>c});var t=r(96540);function o(e,n,r){return n in e?Object.defineProperty(e,n,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[n]=r,e}function a(){return a=Object.assign||function(e){for(var n=1;n=0||(o[r]=e[r]);return o}(e,n);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(o[r]=e[r])}return o}var s=t.createContext({}),c=function(e){return function(n){var r=d(n.components);return t.createElement(e,a({},n,{components:r}))}},d=function(e){var n=t.useContext(s),r=n;return e&&(r="function"==typeof e?e(n):p(p({},n),e)),r},u=function(e){var n=d(e.components);return t.createElement(s.Provider,{value:n},e.children)},m={inlineCode:"code",wrapper:function(e){var n=e.children;return t.createElement(t.Fragment,{},n)}},h=t.forwardRef((function(e,n){var r=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,s=l(e,["components","mdxType","originalType","parentName"]),c=d(r),u=o,h=c["".concat(i,".").concat(u)]||c[u]||m[u]||a;return r?t.createElement(h,p(p({ref:n},s),{},{components:r})):t.createElement(h,p({ref:n},s))}));function f(e,n){var r=arguments,o=n&&n.mdxType;if("string"==typeof e||o){var a=r.length,i=new Array(a);i[0]=h;var p={};for(var l in n)hasOwnProperty.call(n,l)&&(p[l]=n[l]);p.originalType=e,p.mdxType="string"==typeof e?e:o,i[1]=p;for(var s=2;s{r.d(n,{A:()=>l,C:()=>s});var t=r(58168),o=r(96540),a=r(75489),i=r(44586),p=r(74098);function l(e){return o.createElement(a.default,(0,t.A)({},e,{to:(n=e.to,l=(0,p.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(r=null==l?void 0:l.name)?r:"current"]+n),target:"_blank"}));var n,r,l}function s(e){var n,r=null!=(n=e.text)?n:"Example (Click Here)";return o.createElement(l,e,o.createElement("span",null,"\xa0"),o.createElement("img",{src:"https://img.shields.io/badge/-"+r+"-informational",alt:"Example (Click Here)"}))}},43395:(e,n,r)=>{r.r(n),r.d(n,{contentTitle:()=>s,default:()=>m,frontMatter:()=>l,metadata:()=>c,toc:()=>d});var t=r(58168),o=r(98587),a=(r(96540),r(15680)),i=r(49595),p=["components"],l={id:"app_help",title:"Customizing Application's help",sidebar_label:"Customizing Application's help"},s=void 0,c={unversionedId:"configure_hydra/app_help",id:"version-1.3/configure_hydra/app_help",title:"Customizing Application's help",description:"Hydra provides two different help options:",source:"@site/versioned_docs/version-1.3/configure_hydra/app_help.md",sourceDirName:"configure_hydra",slug:"/configure_hydra/app_help",permalink:"/docs/1.3/configure_hydra/app_help",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/configure_hydra/app_help.md",tags:[],version:"1.3",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"app_help",title:"Customizing Application's help",sidebar_label:"Customizing Application's help"},sidebar:"docs",previous:{title:"Customizing working directory pattern",permalink:"/docs/1.3/configure_hydra/workdir"},next:{title:"Colorlog plugin",permalink:"/docs/1.3/plugins/colorlog"}},d=[],u={toc:d};function m(e){var n=e.components,r=(0,o.A)(e,p);return(0,a.mdx)("wrapper",(0,t.A)({},u,r,{components:n,mdxType:"MDXLayout"}),(0,a.mdx)(i.C,{text:"Example application",to:"examples/configure_hydra/custom_help",mdxType:"ExampleGithubLink"}),(0,a.mdx)("p",null,"Hydra provides two different help options:"),(0,a.mdx)("ul",null,(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"--help")," : Application specific help"),(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"--hydra-help")," Hydra specific help. ")),(0,a.mdx)("p",null,"Example output of ",(0,a.mdx)("inlineCode",{parentName:"p"},"--help"),":"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text"},"$ python my_app.py --help\n== AwesomeApp ==\n\nThis is AwesomeApp!\nYou can choose a db driver by appending\n== Configuration groups ==\nCompose your configuration from those groups (db=mysql)\n\ndb: mysql, postgresql\n\n\n== Config ==\nThis is the config generated for this run.\nYou can override everything, for example:\npython my_app.py db.user=foo db.pass=bar\n-------\ndb:\n driver: mysql\n user: omry\n pass: secret\n\n-------\n\nPowered by Hydra (https://hydra.cc)\nUse --hydra-help to view Hydra specific help\n")),(0,a.mdx)("p",null,"This output is generated from the following config group option (selected in ",(0,a.mdx)("inlineCode",{parentName:"p"},"config.yaml")," to be used by default): "),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="hydra/help/my_app_help.yaml"',title:'"hydra/help/my_app_help.yaml"'},"# App name, override to match the name your app is known by\napp_name: AwesomeApp\n\n# Help header, customize to describe your app to your users\nheader: == ${hydra.help.app_name} ==\n\nfooter: |-\n Powered by Hydra (https://hydra.cc)\n Use --hydra-help to view Hydra specific help\n\n# Basic Hydra flags:\n# $FLAGS_HELP\n#\n# Config groups, choose one of:\n# $APP_CONFIG_GROUPS: All config groups that does not start with hydra/.\n# $HYDRA_CONFIG_GROUPS: All the Hydra config groups (starts with hydra/)\n#\n# Configuration generated with overrides:\n# $CONFIG : Generated config\n#\ntemplate: |-\n ${hydra.help.header}\n\n This is ${hydra.help.app_name}!\n You can choose a db driver by appending\n == Configuration groups ==\n Compose your configuration from those groups (db=mysql)\n\n $APP_CONFIG_GROUPS\n\n == Config ==\n This is the config generated for this run.\n You can override everything, for example:\n python my_app.py db.user=foo db.pass=bar\n -------\n $CONFIG\n -------\n \n ${hydra.help.footer}\n")))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/18954878.f056d43d.js b/assets/js/18954878.f056d43d.js new file mode 100644 index 0000000000..1fd89bf637 --- /dev/null +++ b/assets/js/18954878.f056d43d.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[2511],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>d,MDXProvider:()=>p,mdx:()=>f,useMDXComponents:()=>m,withMDXComponents:()=>s});var l=a(96540);function t(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function r(){return r=Object.assign||function(e){for(var n=1;n=0||(t[a]=e[a]);return t}(e,n);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(l=0;l=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(t[a]=e[a])}return t}var d=l.createContext({}),s=function(e){return function(n){var a=m(n.components);return l.createElement(e,r({},n,{components:a}))}},m=function(e){var n=l.useContext(d),a=n;return e&&(a="function"==typeof e?e(n):i(i({},n),e)),a},p=function(e){var n=m(e.components);return l.createElement(d.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return l.createElement(l.Fragment,{},n)}},b=l.forwardRef((function(e,n){var a=e.components,t=e.mdxType,r=e.originalType,o=e.parentName,d=c(e,["components","mdxType","originalType","parentName"]),s=m(a),p=t,b=s["".concat(o,".").concat(p)]||s[p]||u[p]||r;return a?l.createElement(b,i(i({ref:n},d),{},{components:a})):l.createElement(b,i({ref:n},d))}));function f(e,n){var a=arguments,t=n&&n.mdxType;if("string"==typeof e||t){var r=a.length,o=new Array(r);o[0]=b;var i={};for(var c in n)hasOwnProperty.call(n,c)&&(i[c]=n[c]);i.originalType=e,i.mdxType="string"==typeof e?e:t,o[1]=i;for(var d=2;d{a.d(n,{A:()=>c,C:()=>d});var l=a(58168),t=a(96540),r=a(75489),o=a(44586),i=a(74098);function c(e){return t.createElement(r.default,(0,l.A)({},e,{to:(n=e.to,c=(0,i.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(a=null==c?void 0:c.name)?a:"current"]+n),target:"_blank"}));var n,a,c}function d(e){var n,a=null!=(n=e.text)?n:"Example (Click Here)";return t.createElement(c,e,t.createElement("span",null,"\xa0"),t.createElement("img",{src:"https://img.shields.io/badge/-"+a+"-informational",alt:"Example (Click Here)"}))}},49833:(e,n,a)=>{a.r(n),a.d(n,{contentTitle:()=>d,default:()=>u,frontMatter:()=>c,metadata:()=>s,toc:()=>m});var l=a(58168),t=a(98587),r=(a(96540),a(15680)),o=a(49595),i=["components"],c={id:"callbacks",title:"Callbacks",sidebar_label:"Callbacks"},d=void 0,s={unversionedId:"experimental/callbacks",id:"experimental/callbacks",title:"Callbacks",description:"The Callback interface enables custom",source:"@site/docs/experimental/callbacks.md",sourceDirName:"experimental",slug:"/experimental/callbacks",permalink:"/docs/experimental/callbacks",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/experimental/callbacks.md",tags:[],version:"current",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"callbacks",title:"Callbacks",sidebar_label:"Callbacks"},sidebar:"docs",previous:{title:"Introduction",permalink:"/docs/experimental/intro"},next:{title:"Re-run",permalink:"/docs/experimental/rerun"}},m=[{value:"Configure Callback",id:"configure-callback",children:[],level:3},{value:"Callback ordering",id:"callback-ordering",children:[],level:3},{value:"Example callbacks",id:"example-callbacks",children:[],level:3}],p={toc:m};function u(e){var n=e.components,a=(0,t.A)(e,i);return(0,r.mdx)("wrapper",(0,l.A)({},p,a,{components:n,mdxType:"MDXLayout"}),(0,r.mdx)(o.C,{text:"Examples",to:"hydra/experimental/callbacks.py",mdxType:"ExampleGithubLink"}),(0,r.mdx)("p",null,"The ",(0,r.mdx)(o.A,{to:"hydra/experimental/callback.py",mdxType:"GithubLink"},"Callback interface")," enables custom\ncode to be triggered by various Hydra events."),(0,r.mdx)("p",null,"To use the callback API, one should import Hydra's ",(0,r.mdx)("inlineCode",{parentName:"p"},"Callback")," class:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},"from hydra.experimental.callback import Callback\n")),(0,r.mdx)("p",null,"Users can then create subclasses of this ",(0,r.mdx)("inlineCode",{parentName:"p"},"Callback")," class, overriding one or more of\nthe methods defined by ",(0,r.mdx)("inlineCode",{parentName:"p"},"Callback"),". For the methods of a subclass to be called at the\nappropriate time, the subclass must be registered with Hydra in the ",(0,r.mdx)("inlineCode",{parentName:"p"},"hydra.callbacks")," config\n(see examples below)."),(0,r.mdx)("p",null,"The full API exposed by the ",(0,r.mdx)("inlineCode",{parentName:"p"},"hydra.experimental.callback.Callback")," class is listed below:"),(0,r.mdx)("details",null,(0,r.mdx)("summary",null,"Events supported (Click to expand)"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},'from hydra.types import TaskFunction\n\nclass Callback:\n def on_run_start(self, config: DictConfig, **kwargs: Any) -> None:\n """\n Called in RUN mode before job/application code starts. `config` is composed with overrides.\n Some `hydra.runtime` configs are not populated yet.\n See hydra.core.utils.run_job for more info.\n """\n ...\n\n def on_run_end(self, config: DictConfig, **kwargs: Any) -> None:\n """\n Called in RUN mode after job/application code returns.\n """\n ...\n\n def on_multirun_start(self, config: DictConfig, **kwargs: Any) -> None:\n """\n Called in MULTIRUN mode before any job starts.\n When using a launcher, this will be executed on local machine before any Sweeper/Launcher is initialized.\n """\n ...\n\n def on_multirun_end(self, config: DictConfig, **kwargs: Any) -> None:\n """\n Called in MULTIRUN mode after all jobs returns.\n When using a launcher, this will be executed on local machine.\n """\n ...\n\n def on_job_start(self, config: DictConfig, *, task_function: TaskFunction, **kwargs: Any) -> None:\n """\n Called in both RUN and MULTIRUN modes, once for each Hydra job (before running application code).\n This is called from within `hydra.core.utils.run_job`. In the case of remote launching, this will be executed\n on the remote server along with your application code. The `task_function` argument is the function\n decorated with `@hydra.main`.\n """\n ...\n\n def on_job_end(\n self, config: DictConfig, job_return: JobReturn, **kwargs: Any\n ) -> None:\n """\n Called in both RUN and MULTIRUN modes, once for each Hydra job (after running\n application code).\n This is called from within `hydra.core.utils.run_job`. In the case of remote launching, this will be executed\n on the remote server after your application code.\n\n `job_return` contains info that could be useful for logging or post-processing.\n See hydra.core.utils.JobReturn for more.\n """\n ...\n'))),(0,r.mdx)("h3",{id:"configure-callback"},"Configure Callback"),(0,r.mdx)("p",null,"Say we have ",(0,r.mdx)("inlineCode",{parentName:"p"},"MyCallback")," so after every job ends we can upload a certain file to a S3 bucket.\nFor simplicity we include this Callback class within the application, in real life you should have the\nCallback in a separate file.\nRunning the application, we can see our custom method ",(0,r.mdx)("inlineCode",{parentName:"p"},"on_job_end")," was called."),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--9"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app.py"',title:'"my_app.py"'},'class MyCallback(Callback):\n def __init__(self, bucket: str, file_path: str) -> None:\n self.bucket = bucket\n self.file_path = file_path\n\n def on_job_end(self, config: DictConfig, **kwargs: Any) -> None:\n print(f"Job ended,uploading...")\n # uploading...\n\n@hydra.main(version_base=None, config_path="conf", config_name="config")\ndef my_app(cfg: DictConfig) -> None:\n print(OmegaConf.to_yaml(cfg))\n\n\nif __name__ == "__main__":\n my_app()\n'))),(0,r.mdx)("div",{className:"col col--3"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-commandline",metastring:'title="output"',title:'"output"'},"\n$ python my_app.py\nfoo: bar\n\nJob ended,uploading...\n\n\n\n\n\n\n\n\n\n\n\n")))),(0,r.mdx)("p",null,"Now let's take a look at the configurations. "),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-commandline",metastring:'title="$ tree conf"',title:'"$',tree:!0,'conf"':!0},"conf\n\u251c\u2500\u2500 config.yaml\n\u2514\u2500\u2500 hydra\n \u2514\u2500\u2500 callbacks\n \u2514\u2500\u2500 my_callback.yaml\n\n\n"))),(0,r.mdx)("div",{className:"col col--3"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-commandline",metastring:'title="conf/config.yaml"',title:'"conf/config.yaml"'},"defaults:\n - /hydra/callbacks:\n - my_callback\n\nfoo: bar\n\n\n"))),(0,r.mdx)("div",{className:"col col--5"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-commandline",metastring:'title="conf/hydra/callbacks/my_callback.yaml"',title:'"conf/hydra/callbacks/my_callback.yaml"'},"# @package _global_\nhydra:\n callbacks:\n my_callback:\n _target_: my_app.MyCallback\n bucket: my_s3_bucket\n file_path: ./test.pt\n")))),(0,r.mdx)("h3",{id:"callback-ordering"},"Callback ordering"),(0,r.mdx)("p",null,"The ",(0,r.mdx)("inlineCode",{parentName:"p"},"on_run_start")," or ",(0,r.mdx)("inlineCode",{parentName:"p"},"on_multirun_start")," method will get called first,\nfollowed by ",(0,r.mdx)("inlineCode",{parentName:"p"},"on_job_start")," (called once for each job).\nAfter each job ",(0,r.mdx)("inlineCode",{parentName:"p"},"on_job_end")," is called, and finally either ",(0,r.mdx)("inlineCode",{parentName:"p"},"on_run_end")," or\n",(0,r.mdx)("inlineCode",{parentName:"p"},"on_multirun_end")," is called one time before the application exits."),(0,r.mdx)("p",null,"In the ",(0,r.mdx)("inlineCode",{parentName:"p"},"hydra.callbacks")," section of your config, you can use a list to register multiple callbacks. They will be called in the final composed order for ",(0,r.mdx)("inlineCode",{parentName:"p"},"start")," events and\nin reversed order for ",(0,r.mdx)("inlineCode",{parentName:"p"},"end")," events. So, for example, suppose we have the following composed config:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-commandline",metastring:'title="python my_app.py --cfg hydra -p hydra.callbacks"',title:'"python',"my_app.py":!0,"--cfg":!0,hydra:!0,"-p":!0,'hydra.callbacks"':!0},"# @package hydra.callbacks\nmy_callback1:\n _target_: my_app.MyCallback1\n param1: val1\nmy_callback2:\n _target_: my_app.MyCallback2\n param2: val2\n")),(0,r.mdx)("p",null,"Before each job starts, ",(0,r.mdx)("inlineCode",{parentName:"p"},"MyCallback1.on_job_start")," will get called first,\nfollowed by ",(0,r.mdx)("inlineCode",{parentName:"p"},"MyCallback2.on_job_start"),".\nAfter each job ends, ",(0,r.mdx)("inlineCode",{parentName:"p"},"MyCallback2.on_job_end")," will get called first,\nfollowed by ",(0,r.mdx)("inlineCode",{parentName:"p"},"MyCallback1.on_job_end"),"."),(0,r.mdx)("h3",{id:"example-callbacks"},"Example callbacks"),(0,r.mdx)("p",null,"We've included some example callbacks ",(0,r.mdx)(o.A,{to:"hydra/experimental/callbacks.py",mdxType:"GithubLink"},"here"),":"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"LogJobReturnCallback")," is especially useful for logging errors when running on a remote cluster (e.g. slurm.) "),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"PickleJobInfoCallback")," can be used to reproduce a Hydra job. See ",(0,r.mdx)("a",{parentName:"li",href:"/docs/experimental/rerun"},"here")," for more.")))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/18954878.f31e4929.js b/assets/js/18954878.f31e4929.js deleted file mode 100644 index b76ffbaac8..0000000000 --- a/assets/js/18954878.f31e4929.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[2511],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>d,MDXProvider:()=>p,mdx:()=>b,useMDXComponents:()=>m,withMDXComponents:()=>s});var l=a(96540);function t(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function r(){return r=Object.assign||function(e){for(var n=1;n=0||(t[a]=e[a]);return t}(e,n);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(l=0;l=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(t[a]=e[a])}return t}var d=l.createContext({}),s=function(e){return function(n){var a=m(n.components);return l.createElement(e,r({},n,{components:a}))}},m=function(e){var n=l.useContext(d),a=n;return e&&(a="function"==typeof e?e(n):i(i({},n),e)),a},p=function(e){var n=m(e.components);return l.createElement(d.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return l.createElement(l.Fragment,{},n)}},f=l.forwardRef((function(e,n){var a=e.components,t=e.mdxType,r=e.originalType,o=e.parentName,d=c(e,["components","mdxType","originalType","parentName"]),s=m(a),p=t,f=s["".concat(o,".").concat(p)]||s[p]||u[p]||r;return a?l.createElement(f,i(i({ref:n},d),{},{components:a})):l.createElement(f,i({ref:n},d))}));function b(e,n){var a=arguments,t=n&&n.mdxType;if("string"==typeof e||t){var r=a.length,o=new Array(r);o[0]=f;var i={};for(var c in n)hasOwnProperty.call(n,c)&&(i[c]=n[c]);i.originalType=e,i.mdxType="string"==typeof e?e:t,o[1]=i;for(var d=2;d{a.d(n,{A:()=>c,C:()=>d});var l=a(58168),t=a(96540),r=a(75489),o=a(44586),i=a(74098);function c(e){return t.createElement(r.default,(0,l.A)({},e,{to:(n=e.to,c=(0,i.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(a=null==c?void 0:c.name)?a:"current"]+n),target:"_blank"}));var n,a,c}function d(e){var n,a=null!=(n=e.text)?n:"Example (Click Here)";return t.createElement(c,e,t.createElement("span",null,"\xa0"),t.createElement("img",{src:"https://img.shields.io/badge/-"+a+"-informational",alt:"Example (Click Here)"}))}},49833:(e,n,a)=>{a.r(n),a.d(n,{contentTitle:()=>d,default:()=>u,frontMatter:()=>c,metadata:()=>s,toc:()=>m});var l=a(58168),t=a(98587),r=(a(96540),a(15680)),o=a(49595),i=["components"],c={id:"callbacks",title:"Callbacks",sidebar_label:"Callbacks"},d=void 0,s={unversionedId:"experimental/callbacks",id:"experimental/callbacks",title:"Callbacks",description:"The Callback interface enables custom",source:"@site/docs/experimental/callbacks.md",sourceDirName:"experimental",slug:"/experimental/callbacks",permalink:"/docs/experimental/callbacks",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/experimental/callbacks.md",tags:[],version:"current",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"callbacks",title:"Callbacks",sidebar_label:"Callbacks"},sidebar:"docs",previous:{title:"Introduction",permalink:"/docs/experimental/intro"},next:{title:"Re-run",permalink:"/docs/experimental/rerun"}},m=[{value:"Configure Callback",id:"configure-callback",children:[],level:3},{value:"Callback ordering",id:"callback-ordering",children:[],level:3},{value:"Example callbacks",id:"example-callbacks",children:[],level:3}],p={toc:m};function u(e){var n=e.components,a=(0,t.A)(e,i);return(0,r.mdx)("wrapper",(0,l.A)({},p,a,{components:n,mdxType:"MDXLayout"}),(0,r.mdx)(o.C,{text:"Examples",to:"hydra/experimental/callbacks.py",mdxType:"ExampleGithubLink"}),(0,r.mdx)("p",null,"The ",(0,r.mdx)(o.A,{to:"hydra/experimental/callback.py",mdxType:"GithubLink"},"Callback interface")," enables custom\ncode to be triggered by various Hydra events."),(0,r.mdx)("p",null,"To use the callback API, one should import Hydra's ",(0,r.mdx)("inlineCode",{parentName:"p"},"Callback")," class:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},"from hydra.experimental.callback import Callback\n")),(0,r.mdx)("p",null,"Users can then create subclasses of this ",(0,r.mdx)("inlineCode",{parentName:"p"},"Callback")," class, overriding one or more of\nthe methods defined by ",(0,r.mdx)("inlineCode",{parentName:"p"},"Callback"),". For the methods of a subclass to be called at the\nappropriate time, the subclass must be registered with Hydra in the ",(0,r.mdx)("inlineCode",{parentName:"p"},"hydra.callbacks")," config\n(see examples below)."),(0,r.mdx)("p",null,"The full API exposed by the ",(0,r.mdx)("inlineCode",{parentName:"p"},"hydra.experimental.callback.Callback")," class is listed below:"),(0,r.mdx)("details",null,(0,r.mdx)("summary",null,"Events supported (Click to expand)"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python"},'from hydra.types import TaskFunction\n\nclass Callback:\n def on_run_start(self, config: DictConfig, **kwargs: Any) -> None:\n """\n Called in RUN mode before job/application code starts. `config` is composed with overrides.\n Some `hydra.runtime` configs are not populated yet.\n See hydra.core.utils.run_job for more info.\n """\n ...\n\n def on_run_end(self, config: DictConfig, **kwargs: Any) -> None:\n """\n Called in RUN mode after job/application code returns.\n """\n ...\n\n def on_multirun_start(self, config: DictConfig, **kwargs: Any) -> None:\n """\n Called in MULTIRUN mode before any job starts.\n When using a launcher, this will be executed on local machine before any Sweeper/Launcher is initialized.\n """\n ...\n\n def on_multirun_end(self, config: DictConfig, **kwargs: Any) -> None:\n """\n Called in MULTIRUN mode after all jobs returns.\n When using a launcher, this will be executed on local machine.\n """\n ...\n\n def on_job_start(self, config: DictConfig, *, task_function: TaskFunction, **kwargs: Any) -> None:\n """\n Called in both RUN and MULTIRUN modes, once for each Hydra job (before running application code).\n This is called from within `hydra.core.utils.run_job`. In the case of remote launching, this will be executed\n on the remote server along with your application code. The `task_function` argument is the function\n decorated with `@hydra.main`.\n """\n ...\n\n def on_job_end(\n self, config: DictConfig, job_return: JobReturn, **kwargs: Any\n ) -> None:\n """\n Called in both RUN and MULTIRUN modes, once for each Hydra job (after running\n application code).\n This is called from within `hydra.core.utils.run_job`. In the case of remote launching, this will be executed\n on the remote server after your application code.\n\n `job_return` contains info that could be useful for logging or post-processing.\n See hydra.core.utils.JobReturn for more.\n """\n ...\n'))),(0,r.mdx)("h3",{id:"configure-callback"},"Configure Callback"),(0,r.mdx)("p",null,"Say we have ",(0,r.mdx)("inlineCode",{parentName:"p"},"MyCallback")," so after every job ends we can upload a certain file to a S3 bucket.\nFor simplicity we include this Callback class within the application, in real life you should have the\nCallback in a separate file.\nRunning the application, we can see our custom method ",(0,r.mdx)("inlineCode",{parentName:"p"},"on_job_end")," was called."),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--9"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app.py"',title:'"my_app.py"'},'class MyCallback(Callback):\n def __init__(self, bucket: str, file_path: str) -> None:\n self.bucket = bucket\n self.file_path = file_path\n\n def on_job_end(self, config: DictConfig, **kwargs: Any) -> None:\n print(f"Job ended,uploading...")\n # uploading...\n\n@hydra.main(version_base=None, config_path="conf", config_name="config")\ndef my_app(cfg: DictConfig) -> None:\n print(OmegaConf.to_yaml(cfg))\n\n\nif __name__ == "__main__":\n my_app()\n'))),(0,r.mdx)("div",{className:"col col--3"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-commandline",metastring:'title="output"',title:'"output"'},"\n$ python my_app.py\nfoo: bar\n\nJob ended,uploading...\n\n\n\n\n\n\n\n\n\n\n\n")))),(0,r.mdx)("p",null,"Now let's take a look at the configurations. "),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-commandline",metastring:'title="$ tree conf"',title:'"$',tree:!0,'conf"':!0},"conf\n\u251c\u2500\u2500 config.yaml\n\u2514\u2500\u2500 hydra\n \u2514\u2500\u2500 callbacks\n \u2514\u2500\u2500 my_callback.yaml\n\n\n"))),(0,r.mdx)("div",{className:"col col--3"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-commandline",metastring:'title="conf/config.yaml"',title:'"conf/config.yaml"'},"defaults:\n - /hydra/callbacks:\n - my_callback\n\nfoo: bar\n\n\n"))),(0,r.mdx)("div",{className:"col col--5"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-commandline",metastring:'title="conf/hydra/callbacks/my_callback.yaml"',title:'"conf/hydra/callbacks/my_callback.yaml"'},"# @package _global_\nhydra:\n callbacks:\n my_callback:\n _target_: my_app.MyCallback\n bucket: my_s3_bucket\n file_path: ./test.pt\n")))),(0,r.mdx)("h3",{id:"callback-ordering"},"Callback ordering"),(0,r.mdx)("p",null,"The ",(0,r.mdx)("inlineCode",{parentName:"p"},"on_run_start")," or ",(0,r.mdx)("inlineCode",{parentName:"p"},"on_multirun_start")," method will get called first,\nfollowed by ",(0,r.mdx)("inlineCode",{parentName:"p"},"on_job_start")," (called once for each job).\nAfter each job ",(0,r.mdx)("inlineCode",{parentName:"p"},"on_job_end")," is called, and finally either ",(0,r.mdx)("inlineCode",{parentName:"p"},"on_run_end")," or\n",(0,r.mdx)("inlineCode",{parentName:"p"},"on_multirun_end")," is called one time before the application exits."),(0,r.mdx)("p",null,"In the ",(0,r.mdx)("inlineCode",{parentName:"p"},"hydra.callbacks")," section of your config, you can use a list to register multiple callbacks. They will be called in the final composed order for ",(0,r.mdx)("inlineCode",{parentName:"p"},"start")," events and\nin reversed order for ",(0,r.mdx)("inlineCode",{parentName:"p"},"end")," events. So, for example, suppose we have the following composed config:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-commandline",metastring:'title="python my_app.py --cfg hydra -p hydra.callbacks"',title:'"python',"my_app.py":!0,"--cfg":!0,hydra:!0,"-p":!0,'hydra.callbacks"':!0},"# @package hydra.callbacks\nmy_callback1:\n _target_: my_app.MyCallback1\n param1: val1\nmy_callback2:\n _target_: my_app.MyCallback2\n param2: val2\n")),(0,r.mdx)("p",null,"Before each job starts, ",(0,r.mdx)("inlineCode",{parentName:"p"},"MyCallback1.on_job_start")," will get called first,\nfollowed by ",(0,r.mdx)("inlineCode",{parentName:"p"},"MyCallback2.on_job_start"),".\nAfter each job ends, ",(0,r.mdx)("inlineCode",{parentName:"p"},"MyCallback2.on_job_end")," will get called first,\nfollowed by ",(0,r.mdx)("inlineCode",{parentName:"p"},"MyCallback1.on_job_end"),"."),(0,r.mdx)("h3",{id:"example-callbacks"},"Example callbacks"),(0,r.mdx)("p",null,"We've included some example callbacks ",(0,r.mdx)(o.A,{to:"hydra/experimental/callbacks.py",mdxType:"GithubLink"},"here"),":"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"LogJobReturnCallback")," is especially useful for logging errors when running on a remote cluster (e.g. slurm.) "),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"PickleJobInfoCallback")," can be used to reproduce a Hydra job. See ",(0,r.mdx)("a",{parentName:"li",href:"/docs/experimental/rerun"},"here")," for more.")))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/18d93f34.9d16cd59.js b/assets/js/18d93f34.9d16cd59.js new file mode 100644 index 0000000000..f72c5f299a --- /dev/null +++ b/assets/js/18d93f34.9d16cd59.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3711],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>m,MDXProvider:()=>d,mdx:()=>y,useMDXComponents:()=>c,withMDXComponents:()=>p});var o=t(96540);function r(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function a(){return a=Object.assign||function(e){for(var n=1;n=0||(r[t]=e[t]);return r}(e,n);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(o=0;o=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(r[t]=e[t])}return r}var m=o.createContext({}),p=function(e){return function(n){var t=c(n.components);return o.createElement(e,a({},n,{components:t}))}},c=function(e){var n=o.useContext(m),t=n;return e&&(t="function"==typeof e?e(n):s(s({},n),e)),t},d=function(e){var n=c(e.components);return o.createElement(m.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return o.createElement(o.Fragment,{},n)}},f=o.forwardRef((function(e,n){var t=e.components,r=e.mdxType,a=e.originalType,i=e.parentName,m=l(e,["components","mdxType","originalType","parentName"]),p=c(t),d=r,f=p["".concat(i,".").concat(d)]||p[d]||u[d]||a;return t?o.createElement(f,s(s({ref:n},m),{},{components:t})):o.createElement(f,s({ref:n},m))}));function y(e,n){var t=arguments,r=n&&n.mdxType;if("string"==typeof e||r){var a=t.length,i=new Array(a);i[0]=f;var s={};for(var l in n)hasOwnProperty.call(n,l)&&(s[l]=n[l]);s.originalType=e,s.mdxType="string"==typeof e?e:r,i[1]=s;for(var m=2;m{t.r(n),t.d(n,{contentTitle:()=>l,default:()=>d,frontMatter:()=>s,metadata:()=>m,toc:()=>p});var o=t(58168),r=t(98587),a=(t(96540),t(15680)),i=["components"],s={id:"composition",title:"Config composition",sidebar_label:"Config composition"},l=void 0,m={unversionedId:"tutorial/composition",id:"version-0.11/tutorial/composition",title:"Config composition",description:"As software gets more complex, we resort to modularity and composition to keep it manageable.",source:"@site/versioned_docs/version-0.11/tutorial/5_composition.md",sourceDirName:"tutorial",slug:"/tutorial/composition",permalink:"/docs/0.11/tutorial/composition",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-0.11/tutorial/5_composition.md",tags:[],version:"0.11",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:5,frontMatter:{id:"composition",title:"Config composition",sidebar_label:"Config composition"},sidebar:"version-0.11/docs",previous:{title:"Defaults",permalink:"/docs/0.11/tutorial/defaults"},next:{title:"Multi-run",permalink:"/docs/0.11/tutorial/multi-run"}},p=[],c={toc:p};function d(e){var n=e.components,t=(0,r.A)(e,i);return(0,a.mdx)("wrapper",(0,o.A)({},c,t,{components:n,mdxType:"MDXLayout"}),(0,a.mdx)("p",null,"As software gets more complex, we resort to modularity and composition to keep it manageable.\nWe can do the same with configs: suppose we want our working example to support multiple databases, with\nmultiple schemas per database, and different UIs. We wouldn't write a separate class\nfor each permutation of db, schema and UI, so we shouldn't write separate configs either. We use\nthe same solution in configuration as in writing the underlying software: composition. "),(0,a.mdx)("p",null,"To do this in Hydra, we first add a ",(0,a.mdx)("inlineCode",{parentName:"p"},"schema")," and a ",(0,a.mdx)("inlineCode",{parentName:"p"},"ui")," config group:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text"},"\u251c\u2500\u2500 conf\n\u2502\xa0\xa0 \u251c\u2500\u2500 config.yaml\n\u2502\xa0\xa0 \u251c\u2500\u2500 db\n\u2502\xa0\xa0 \u2502\xa0\xa0 \u251c\u2500\u2500 mysql.yaml\n\u2502\xa0\xa0 \u2502\xa0\xa0 \u2514\u2500\u2500 postgresql.yaml\n\u2502\xa0\xa0 \u251c\u2500\u2500 schema\n\u2502\xa0\xa0 \u2502\xa0\xa0 \u251c\u2500\u2500 school.yaml\n\u2502\xa0\xa0 \u2502\xa0\xa0 \u251c\u2500\u2500 support.yaml\n\u2502\xa0\xa0 \u2502\xa0\xa0 \u2514\u2500\u2500 warehouse.yaml\n\u2502\xa0\xa0 \u2514\u2500\u2500 ui\n\u2502\xa0\xa0 \u251c\u2500\u2500 full.yaml\n\u2502\xa0\xa0 \u2514\u2500\u2500 view.yaml\n\u2514\u2500\u2500 my_app.py\n")),(0,a.mdx)("p",null,"With these configs, we already have 12 possible combinations. Without composition we would need 12 separate configs,\nand a single change (such as renaming ",(0,a.mdx)("inlineCode",{parentName:"p"},"db.user")," to ",(0,a.mdx)("inlineCode",{parentName:"p"},"db.username"),") would need to be done separately in every one of them. "),(0,a.mdx)("p",null,"This is a maintainability nightmare -- but composition can come to the rescue."),(0,a.mdx)("p",null,"Configuration file: ",(0,a.mdx)("inlineCode",{parentName:"p"},"config.yaml")),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - db: mysql\n - ui: full\n - schema: school\n")),(0,a.mdx)("p",null,"The defaults are ordered:"),(0,a.mdx)("ul",null,(0,a.mdx)("li",{parentName:"ul"},"If there are two configurations that defines the same value, the second one would win. "),(0,a.mdx)("li",{parentName:"ul"},"If two configurations are contributing to the same dictionary the result would be the combined dictionary.")),(0,a.mdx)("p",null,"When running this, we will compose a configuration with ",(0,a.mdx)("inlineCode",{parentName:"p"},"mysql"),", ",(0,a.mdx)("inlineCode",{parentName:"p"},"full")," ui and the ",(0,a.mdx)("inlineCode",{parentName:"p"},"school")," database schema (which we are seeing for the first time here):"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py\ndb:\n driver: mysql\n pass: secret\n user: omry\nschema:\n database: school\n tables:\n - fields:\n - name: string\n - class: int\n name: students\n - fields:\n - profession: string\n - time: data\n - class: int\n name: exams\nui:\n windows:\n create_db: true\n view: true\n")),(0,a.mdx)("p",null,"In much the same way you can compose any of the other 11 configurations by adding appropriate overrides such as ",(0,a.mdx)("inlineCode",{parentName:"p"},"db=postgresql"),"."))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/18d93f34.fa466898.js b/assets/js/18d93f34.fa466898.js deleted file mode 100644 index 92a792cc63..0000000000 --- a/assets/js/18d93f34.fa466898.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3711],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>m,MDXProvider:()=>u,mdx:()=>y,useMDXComponents:()=>c,withMDXComponents:()=>p});var o=t(96540);function r(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function a(){return a=Object.assign||function(e){for(var n=1;n=0||(r[t]=e[t]);return r}(e,n);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(o=0;o=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(r[t]=e[t])}return r}var m=o.createContext({}),p=function(e){return function(n){var t=c(n.components);return o.createElement(e,a({},n,{components:t}))}},c=function(e){var n=o.useContext(m),t=n;return e&&(t="function"==typeof e?e(n):s(s({},n),e)),t},u=function(e){var n=c(e.components);return o.createElement(m.Provider,{value:n},e.children)},d={inlineCode:"code",wrapper:function(e){var n=e.children;return o.createElement(o.Fragment,{},n)}},f=o.forwardRef((function(e,n){var t=e.components,r=e.mdxType,a=e.originalType,i=e.parentName,m=l(e,["components","mdxType","originalType","parentName"]),p=c(t),u=r,f=p["".concat(i,".").concat(u)]||p[u]||d[u]||a;return t?o.createElement(f,s(s({ref:n},m),{},{components:t})):o.createElement(f,s({ref:n},m))}));function y(e,n){var t=arguments,r=n&&n.mdxType;if("string"==typeof e||r){var a=t.length,i=new Array(a);i[0]=f;var s={};for(var l in n)hasOwnProperty.call(n,l)&&(s[l]=n[l]);s.originalType=e,s.mdxType="string"==typeof e?e:r,i[1]=s;for(var m=2;m{t.r(n),t.d(n,{contentTitle:()=>l,default:()=>u,frontMatter:()=>s,metadata:()=>m,toc:()=>p});var o=t(58168),r=t(98587),a=(t(96540),t(15680)),i=["components"],s={id:"composition",title:"Config composition",sidebar_label:"Config composition"},l=void 0,m={unversionedId:"tutorial/composition",id:"version-0.11/tutorial/composition",title:"Config composition",description:"As software gets more complex, we resort to modularity and composition to keep it manageable.",source:"@site/versioned_docs/version-0.11/tutorial/5_composition.md",sourceDirName:"tutorial",slug:"/tutorial/composition",permalink:"/docs/0.11/tutorial/composition",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-0.11/tutorial/5_composition.md",tags:[],version:"0.11",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:5,frontMatter:{id:"composition",title:"Config composition",sidebar_label:"Config composition"},sidebar:"version-0.11/docs",previous:{title:"Defaults",permalink:"/docs/0.11/tutorial/defaults"},next:{title:"Multi-run",permalink:"/docs/0.11/tutorial/multi-run"}},p=[],c={toc:p};function u(e){var n=e.components,t=(0,r.A)(e,i);return(0,a.mdx)("wrapper",(0,o.A)({},c,t,{components:n,mdxType:"MDXLayout"}),(0,a.mdx)("p",null,"As software gets more complex, we resort to modularity and composition to keep it manageable.\nWe can do the same with configs: suppose we want our working example to support multiple databases, with\nmultiple schemas per database, and different UIs. We wouldn't write a separate class\nfor each permutation of db, schema and UI, so we shouldn't write separate configs either. We use\nthe same solution in configuration as in writing the underlying software: composition. "),(0,a.mdx)("p",null,"To do this in Hydra, we first add a ",(0,a.mdx)("inlineCode",{parentName:"p"},"schema")," and a ",(0,a.mdx)("inlineCode",{parentName:"p"},"ui")," config group:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text"},"\u251c\u2500\u2500 conf\n\u2502\xa0\xa0 \u251c\u2500\u2500 config.yaml\n\u2502\xa0\xa0 \u251c\u2500\u2500 db\n\u2502\xa0\xa0 \u2502\xa0\xa0 \u251c\u2500\u2500 mysql.yaml\n\u2502\xa0\xa0 \u2502\xa0\xa0 \u2514\u2500\u2500 postgresql.yaml\n\u2502\xa0\xa0 \u251c\u2500\u2500 schema\n\u2502\xa0\xa0 \u2502\xa0\xa0 \u251c\u2500\u2500 school.yaml\n\u2502\xa0\xa0 \u2502\xa0\xa0 \u251c\u2500\u2500 support.yaml\n\u2502\xa0\xa0 \u2502\xa0\xa0 \u2514\u2500\u2500 warehouse.yaml\n\u2502\xa0\xa0 \u2514\u2500\u2500 ui\n\u2502\xa0\xa0 \u251c\u2500\u2500 full.yaml\n\u2502\xa0\xa0 \u2514\u2500\u2500 view.yaml\n\u2514\u2500\u2500 my_app.py\n")),(0,a.mdx)("p",null,"With these configs, we already have 12 possible combinations. Without composition we would need 12 separate configs,\nand a single change (such as renaming ",(0,a.mdx)("inlineCode",{parentName:"p"},"db.user")," to ",(0,a.mdx)("inlineCode",{parentName:"p"},"db.username"),") would need to be done separately in every one of them. "),(0,a.mdx)("p",null,"This is a maintainability nightmare -- but composition can come to the rescue."),(0,a.mdx)("p",null,"Configuration file: ",(0,a.mdx)("inlineCode",{parentName:"p"},"config.yaml")),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - db: mysql\n - ui: full\n - schema: school\n")),(0,a.mdx)("p",null,"The defaults are ordered:"),(0,a.mdx)("ul",null,(0,a.mdx)("li",{parentName:"ul"},"If there are two configurations that defines the same value, the second one would win. "),(0,a.mdx)("li",{parentName:"ul"},"If two configurations are contributing to the same dictionary the result would be the combined dictionary.")),(0,a.mdx)("p",null,"When running this, we will compose a configuration with ",(0,a.mdx)("inlineCode",{parentName:"p"},"mysql"),", ",(0,a.mdx)("inlineCode",{parentName:"p"},"full")," ui and the ",(0,a.mdx)("inlineCode",{parentName:"p"},"school")," database schema (which we are seeing for the first time here):"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py\ndb:\n driver: mysql\n pass: secret\n user: omry\nschema:\n database: school\n tables:\n - fields:\n - name: string\n - class: int\n name: students\n - fields:\n - profession: string\n - time: data\n - class: int\n name: exams\nui:\n windows:\n create_db: true\n view: true\n")),(0,a.mdx)("p",null,"In much the same way you can compose any of the other 11 configurations by adding appropriate overrides such as ",(0,a.mdx)("inlineCode",{parentName:"p"},"db=postgresql"),"."))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1b0e2224.2549507c.js b/assets/js/1b0e2224.2549507c.js new file mode 100644 index 0000000000..568de20680 --- /dev/null +++ b/assets/js/1b0e2224.2549507c.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[7397],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>p,MDXProvider:()=>d,mdx:()=>b,useMDXComponents:()=>u,withMDXComponents:()=>s});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(){return i=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var p=r.createContext({}),s=function(e){return function(t){var n=u(t.components);return r.createElement(e,i({},t,{components:n}))}},u=function(e){var t=r.useContext(p),n=t;return e&&(n="function"==typeof e?e(t):c(c({},t),e)),n},d=function(e){var t=u(e.components);return r.createElement(p.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},f=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,i=e.originalType,a=e.parentName,p=l(e,["components","mdxType","originalType","parentName"]),s=u(n),d=o,f=s["".concat(a,".").concat(d)]||s[d]||m[d]||i;return n?r.createElement(f,c(c({ref:t},p),{},{components:n})):r.createElement(f,c({ref:t},p))}));function b(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var i=n.length,a=new Array(i);a[0]=f;var c={};for(var l in t)hasOwnProperty.call(t,l)&&(c[l]=t[l]);c.originalType=e,c.mdxType="string"==typeof e?e:o,a[1]=c;for(var p=2;p{n.d(t,{A:()=>o});var r=n(96540);function o(e){var t=(0,r.useRef)(null),n=(0,r.useRef)("undefined"!=typeof document?document.createElement("script"):null);return(0,r.useEffect)((function(){t.current.appendChild(n.current)}),[]),(0,r.useEffect)((function(){for(var t in e)e.hasOwnProperty(t)&&(n.current[t]=e[t])})),r.createElement("div",{ref:t})}},17631:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>p,default:()=>m,frontMatter:()=>l,metadata:()=>s,toc:()=>u});var r=n(58168),o=n(98587),i=(n(96540),n(15680)),a=n(57259),c=["components"],l={id:"tab_completion",title:"Tab completion",sidebar_label:"Tab completion"},p=void 0,s={unversionedId:"tutorials/basic/running_your_app/tab_completion",id:"version-1.0/tutorials/basic/running_your_app/tab_completion",title:"Tab completion",description:"Tab completion can complete config groups, config nodes and values.",source:"@site/versioned_docs/version-1.0/tutorials/basic/running_your_app/6_tab_completion.md",sourceDirName:"tutorials/basic/running_your_app",slug:"/tutorials/basic/running_your_app/tab_completion",permalink:"/docs/1.0/tutorials/basic/running_your_app/tab_completion",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.0/tutorials/basic/running_your_app/6_tab_completion.md",tags:[],version:"1.0",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:6,frontMatter:{id:"tab_completion",title:"Tab completion",sidebar_label:"Tab completion"},sidebar:"version-1.0/docs",previous:{title:"Debugging",permalink:"/docs/1.0/tutorials/basic/running_your_app/debugging"},next:{title:"Introduction to Structured Configs",permalink:"/docs/1.0/tutorials/structured_config/intro"}},u=[{value:"Install tab completion",id:"install-tab-completion",children:[],level:3}],d={toc:u};function m(e){var t=e.components,n=(0,o.A)(e,c);return(0,i.mdx)("wrapper",(0,r.A)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Tab completion can complete config groups, config nodes and values.\nTo complete paths, start them with ",(0,i.mdx)("inlineCode",{parentName:"p"},"/")," or ",(0,i.mdx)("inlineCode",{parentName:"p"},"./"),"."),(0,i.mdx)("p",null,"See this short video demonstration of tab completion:"),(0,i.mdx)(a.A,{id:"asciicast-272604",src:"https://asciinema.org/a/272604.js",async:!0,mdxType:"Script"}),(0,i.mdx)("h3",{id:"install-tab-completion"},"Install tab completion"),(0,i.mdx)("p",null,"Get the exact command to install the completion from ",(0,i.mdx)("inlineCode",{parentName:"p"},"python --hydra-help"),".\nCurrently, Bash and Fish are supported. We are relying on the community to implement completion plugins for additional shells."),(0,i.mdx)("p",null,"Fish support requires version >= 3.1.2.\nPrevious versions will work but add an extra space after ",(0,i.mdx)("inlineCode",{parentName:"p"},"."),"."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1b0e2224.9a06263e.js b/assets/js/1b0e2224.9a06263e.js deleted file mode 100644 index 14b72ab13a..0000000000 --- a/assets/js/1b0e2224.9a06263e.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[7397],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>p,MDXProvider:()=>m,mdx:()=>b,useMDXComponents:()=>u,withMDXComponents:()=>s});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(){return i=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var p=r.createContext({}),s=function(e){return function(t){var n=u(t.components);return r.createElement(e,i({},t,{components:n}))}},u=function(e){var t=r.useContext(p),n=t;return e&&(n="function"==typeof e?e(t):c(c({},t),e)),n},m=function(e){var t=u(e.components);return r.createElement(p.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},f=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,i=e.originalType,a=e.parentName,p=l(e,["components","mdxType","originalType","parentName"]),s=u(n),m=o,f=s["".concat(a,".").concat(m)]||s[m]||d[m]||i;return n?r.createElement(f,c(c({ref:t},p),{},{components:n})):r.createElement(f,c({ref:t},p))}));function b(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var i=n.length,a=new Array(i);a[0]=f;var c={};for(var l in t)hasOwnProperty.call(t,l)&&(c[l]=t[l]);c.originalType=e,c.mdxType="string"==typeof e?e:o,a[1]=c;for(var p=2;p{n.d(t,{A:()=>o});var r=n(96540);function o(e){var t=(0,r.useRef)(null),n=(0,r.useRef)("undefined"!=typeof document?document.createElement("script"):null);return(0,r.useEffect)((function(){t.current.appendChild(n.current)}),[]),(0,r.useEffect)((function(){for(var t in e)e.hasOwnProperty(t)&&(n.current[t]=e[t])})),r.createElement("div",{ref:t})}},17631:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>p,default:()=>d,frontMatter:()=>l,metadata:()=>s,toc:()=>u});var r=n(58168),o=n(98587),i=(n(96540),n(15680)),a=n(57259),c=["components"],l={id:"tab_completion",title:"Tab completion",sidebar_label:"Tab completion"},p=void 0,s={unversionedId:"tutorials/basic/running_your_app/tab_completion",id:"version-1.0/tutorials/basic/running_your_app/tab_completion",title:"Tab completion",description:"Tab completion can complete config groups, config nodes and values.",source:"@site/versioned_docs/version-1.0/tutorials/basic/running_your_app/6_tab_completion.md",sourceDirName:"tutorials/basic/running_your_app",slug:"/tutorials/basic/running_your_app/tab_completion",permalink:"/docs/1.0/tutorials/basic/running_your_app/tab_completion",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.0/tutorials/basic/running_your_app/6_tab_completion.md",tags:[],version:"1.0",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:6,frontMatter:{id:"tab_completion",title:"Tab completion",sidebar_label:"Tab completion"},sidebar:"version-1.0/docs",previous:{title:"Debugging",permalink:"/docs/1.0/tutorials/basic/running_your_app/debugging"},next:{title:"Introduction to Structured Configs",permalink:"/docs/1.0/tutorials/structured_config/intro"}},u=[{value:"Install tab completion",id:"install-tab-completion",children:[],level:3}],m={toc:u};function d(e){var t=e.components,n=(0,o.A)(e,c);return(0,i.mdx)("wrapper",(0,r.A)({},m,n,{components:t,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Tab completion can complete config groups, config nodes and values.\nTo complete paths, start them with ",(0,i.mdx)("inlineCode",{parentName:"p"},"/")," or ",(0,i.mdx)("inlineCode",{parentName:"p"},"./"),"."),(0,i.mdx)("p",null,"See this short video demonstration of tab completion:"),(0,i.mdx)(a.A,{id:"asciicast-272604",src:"https://asciinema.org/a/272604.js",async:!0,mdxType:"Script"}),(0,i.mdx)("h3",{id:"install-tab-completion"},"Install tab completion"),(0,i.mdx)("p",null,"Get the exact command to install the completion from ",(0,i.mdx)("inlineCode",{parentName:"p"},"python --hydra-help"),".\nCurrently, Bash and Fish are supported. We are relying on the community to implement completion plugins for additional shells."),(0,i.mdx)("p",null,"Fish support requires version >= 3.1.2.\nPrevious versions will work but add an extra space after ",(0,i.mdx)("inlineCode",{parentName:"p"},"."),"."))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1c10768b.475b3bcc.js b/assets/js/1c10768b.475b3bcc.js new file mode 100644 index 0000000000..0ffea776d5 --- /dev/null +++ b/assets/js/1c10768b.475b3bcc.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[4429],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>d,MDXProvider:()=>c,mdx:()=>f,useMDXComponents:()=>m,withMDXComponents:()=>p});var o=n(96540);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(){return i=Object.assign||function(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(o=0;o=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var d=o.createContext({}),p=function(e){return function(t){var n=m(t.components);return o.createElement(e,i({},t,{components:n}))}},m=function(e){var t=o.useContext(d),n=t;return e&&(n="function"==typeof e?e(t):s(s({},t),e)),n},c=function(e){var t=m(e.components);return o.createElement(d.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return o.createElement(o.Fragment,{},t)}},v=o.forwardRef((function(e,t){var n=e.components,r=e.mdxType,i=e.originalType,a=e.parentName,d=l(e,["components","mdxType","originalType","parentName"]),p=m(n),c=r,v=p["".concat(a,".").concat(c)]||p[c]||u[c]||i;return n?o.createElement(v,s(s({ref:t},d),{},{components:n})):o.createElement(v,s({ref:t},d))}));function f(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var i=n.length,a=new Array(i);a[0]=v;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s.mdxType="string"==typeof e?e:r,a[1]=s;for(var d=2;d{n.r(t),n.d(t,{contentTitle:()=>l,default:()=>c,frontMatter:()=>s,metadata:()=>d,toc:()=>p});var o=n(58168),r=n(98587),i=(n(96540),n(15680)),a=["components"],s={id:"testing",title:"Testing",sidebar_label:"Testing"},l=void 0,d={unversionedId:"development/testing",id:"version-1.0/development/testing",title:"Testing",description:"Hydra uses a test automation tool called nox to manage tests, linting, code coverage, etc.",source:"@site/versioned_docs/version-1.0/development/testing.md",sourceDirName:"development",slug:"/development/testing",permalink:"/docs/1.0/development/testing",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.0/development/testing.md",tags:[],version:"1.0",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"testing",title:"Testing",sidebar_label:"Testing"},sidebar:"version-1.0/docs",previous:{title:"Overview",permalink:"/docs/1.0/development/overview"},next:{title:"Style Guide",permalink:"/docs/1.0/development/style_guide"}},p=[{value:"With pytest",id:"with-pytest",children:[],level:2},{value:"With nox",id:"with-nox",children:[],level:2}],m={toc:p};function c(e){var t=e.components,n=(0,r.A)(e,a);return(0,i.mdx)("wrapper",(0,o.A)({},m,n,{components:t,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Hydra uses a test automation tool called ",(0,i.mdx)("a",{parentName:"p",href:"https://github.com/theacodes/nox"},"nox")," to manage tests, linting, code coverage, etc.\n",(0,i.mdx)("inlineCode",{parentName:"p"},"nox")," will run all the configured sessions. You can see the full list of nox sessions with ",(0,i.mdx)("inlineCode",{parentName:"p"},"nox -l")," and run specific sessions\nwith ",(0,i.mdx)("inlineCode",{parentName:"p"},"nox -s NAME")," (you may need to quote the session name in some cases)"),(0,i.mdx)("h2",{id:"with-pytest"},"With pytest"),(0,i.mdx)("p",null,"Run ",(0,i.mdx)("inlineCode",{parentName:"p"},"pytest")," at the repository root to run all the Hydra core tests.\nTo run the tests of individual plugins, use ",(0,i.mdx)("inlineCode",{parentName:"p"},"pytest plugins/NAME"),"."),(0,i.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,i.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,i.mdx)("h5",{parentName:"div"},(0,i.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,i.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,i.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"NOTE")),(0,i.mdx)("div",{parentName:"div",className:"admonition-content"},(0,i.mdx)("p",{parentName:"div"},"Some plugins support fewer versions of Python than the Hydra core."))),(0,i.mdx)("h2",{id:"with-nox"},"With nox"),(0,i.mdx)("p",null,"See ",(0,i.mdx)("inlineCode",{parentName:"p"},"nox -l"),". a few examples:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"nox -s test_core")," will test Hydra core on all supported Python versions"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},'nox -s "test_core-3.6(pip install)"')," : Test on Python 3.6 with ",(0,i.mdx)("inlineCode",{parentName:"li"},"pip install")," as installation method"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},'nox -s "test_plugins-3.8(pip install -e)"')," : Test plugins on Python 3.8 with ",(0,i.mdx)("inlineCode",{parentName:"li"},"pip install -e")," as installation method")))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1c10768b.f9840c56.js b/assets/js/1c10768b.f9840c56.js deleted file mode 100644 index 9b7beef069..0000000000 --- a/assets/js/1c10768b.f9840c56.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[4429],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>p,MDXProvider:()=>c,mdx:()=>f,useMDXComponents:()=>m,withMDXComponents:()=>d});var o=n(96540);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(){return i=Object.assign||function(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(o=0;o=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var p=o.createContext({}),d=function(e){return function(t){var n=m(t.components);return o.createElement(e,i({},t,{components:n}))}},m=function(e){var t=o.useContext(p),n=t;return e&&(n="function"==typeof e?e(t):s(s({},t),e)),n},c=function(e){var t=m(e.components);return o.createElement(p.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return o.createElement(o.Fragment,{},t)}},v=o.forwardRef((function(e,t){var n=e.components,r=e.mdxType,i=e.originalType,a=e.parentName,p=l(e,["components","mdxType","originalType","parentName"]),d=m(n),c=r,v=d["".concat(a,".").concat(c)]||d[c]||u[c]||i;return n?o.createElement(v,s(s({ref:t},p),{},{components:n})):o.createElement(v,s({ref:t},p))}));function f(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var i=n.length,a=new Array(i);a[0]=v;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s.mdxType="string"==typeof e?e:r,a[1]=s;for(var p=2;p{n.r(t),n.d(t,{contentTitle:()=>l,default:()=>c,frontMatter:()=>s,metadata:()=>p,toc:()=>d});var o=n(58168),r=n(98587),i=(n(96540),n(15680)),a=["components"],s={id:"testing",title:"Testing",sidebar_label:"Testing"},l=void 0,p={unversionedId:"development/testing",id:"version-1.0/development/testing",title:"Testing",description:"Hydra uses a test automation tool called nox to manage tests, linting, code coverage, etc.",source:"@site/versioned_docs/version-1.0/development/testing.md",sourceDirName:"development",slug:"/development/testing",permalink:"/docs/1.0/development/testing",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.0/development/testing.md",tags:[],version:"1.0",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"testing",title:"Testing",sidebar_label:"Testing"},sidebar:"version-1.0/docs",previous:{title:"Overview",permalink:"/docs/1.0/development/overview"},next:{title:"Style Guide",permalink:"/docs/1.0/development/style_guide"}},d=[{value:"With pytest",id:"with-pytest",children:[],level:2},{value:"With nox",id:"with-nox",children:[],level:2}],m={toc:d};function c(e){var t=e.components,n=(0,r.A)(e,a);return(0,i.mdx)("wrapper",(0,o.A)({},m,n,{components:t,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Hydra uses a test automation tool called ",(0,i.mdx)("a",{parentName:"p",href:"https://github.com/theacodes/nox"},"nox")," to manage tests, linting, code coverage, etc.\n",(0,i.mdx)("inlineCode",{parentName:"p"},"nox")," will run all the configured sessions. You can see the full list of nox sessions with ",(0,i.mdx)("inlineCode",{parentName:"p"},"nox -l")," and run specific sessions\nwith ",(0,i.mdx)("inlineCode",{parentName:"p"},"nox -s NAME")," (you may need to quote the session name in some cases)"),(0,i.mdx)("h2",{id:"with-pytest"},"With pytest"),(0,i.mdx)("p",null,"Run ",(0,i.mdx)("inlineCode",{parentName:"p"},"pytest")," at the repository root to run all the Hydra core tests.\nTo run the tests of individual plugins, use ",(0,i.mdx)("inlineCode",{parentName:"p"},"pytest plugins/NAME"),"."),(0,i.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,i.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,i.mdx)("h5",{parentName:"div"},(0,i.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,i.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,i.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"NOTE")),(0,i.mdx)("div",{parentName:"div",className:"admonition-content"},(0,i.mdx)("p",{parentName:"div"},"Some plugins support fewer versions of Python than the Hydra core."))),(0,i.mdx)("h2",{id:"with-nox"},"With nox"),(0,i.mdx)("p",null,"See ",(0,i.mdx)("inlineCode",{parentName:"p"},"nox -l"),". a few examples:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"nox -s test_core")," will test Hydra core on all supported Python versions"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},'nox -s "test_core-3.6(pip install)"')," : Test on Python 3.6 with ",(0,i.mdx)("inlineCode",{parentName:"li"},"pip install")," as installation method"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},'nox -s "test_plugins-3.8(pip install -e)"')," : Test plugins on Python 3.8 with ",(0,i.mdx)("inlineCode",{parentName:"li"},"pip install -e")," as installation method")))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1c50c1b8.9f0fd292.js b/assets/js/1c50c1b8.9f0fd292.js new file mode 100644 index 0000000000..019d5b7c54 --- /dev/null +++ b/assets/js/1c50c1b8.9f0fd292.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[7774],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>d,MDXProvider:()=>u,mdx:()=>g,useMDXComponents:()=>p,withMDXComponents:()=>m});var a=n(96540);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var d=a.createContext({}),m=function(e){return function(t){var n=p(t.components);return a.createElement(e,o({},t,{components:n}))}},p=function(e){var t=a.useContext(d),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},u=function(e){var t=p(e.components);return a.createElement(d.Provider,{value:t},e.children)},c={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},f=a.forwardRef((function(e,t){var n=e.components,i=e.mdxType,o=e.originalType,r=e.parentName,d=s(e,["components","mdxType","originalType","parentName"]),m=p(n),u=i,f=m["".concat(r,".").concat(u)]||m[u]||c[u]||o;return n?a.createElement(f,l(l({ref:t},d),{},{components:n})):a.createElement(f,l({ref:t},d))}));function g(e,t){var n=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var o=n.length,r=new Array(o);r[0]=f;var l={};for(var s in t)hasOwnProperty.call(t,s)&&(l[s]=t[s]);l.originalType=e,l.mdxType="string"==typeof e?e:i,r[1]=l;for(var d=2;d{n.d(t,{A:()=>s,C:()=>d});var a=n(58168),i=n(96540),o=n(75489),r=n(44586),l=n(74098);function s(e){return i.createElement(o.default,(0,a.A)({},e,{to:(t=e.to,s=(0,l.useActiveVersion)(),(0,r.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==s?void 0:s.name)?n:"current"]+t),target:"_blank"}));var t,n,s}function d(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return i.createElement(s,e,i.createElement("span",null,"\xa0"),i.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},33302:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>d,default:()=>c,frontMatter:()=>s,metadata:()=>m,toc:()=>p});var a=n(58168),i=n(98587),o=(n(96540),n(15680)),r=n(49595),l=["components"],s={id:"defaults",title:"Selecting default configs"},d=void 0,m={unversionedId:"tutorials/basic/your_first_app/defaults",id:"tutorials/basic/your_first_app/defaults",title:"Selecting default configs",description:"After office politics, you decide that you want to use MySQL by default.",source:"@site/docs/tutorials/basic/your_first_app/5_defaults.md",sourceDirName:"tutorials/basic/your_first_app",slug:"/tutorials/basic/your_first_app/defaults",permalink:"/docs/tutorials/basic/your_first_app/defaults",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/tutorials/basic/your_first_app/5_defaults.md",tags:[],version:"current",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:5,frontMatter:{id:"defaults",title:"Selecting default configs"},sidebar:"docs",previous:{title:"Grouping config files",permalink:"/docs/tutorials/basic/your_first_app/config_groups"},next:{title:"Putting it all together",permalink:"/docs/tutorials/basic/your_first_app/composition"}},p=[{value:"Config group defaults",id:"config-group-defaults",children:[{value:"Overriding a config group default",id:"overriding-a-config-group-default",children:[],level:4}],level:3},{value:"Composition order of primary config",id:"composition-order-of-primary-config",children:[],level:3},{value:"Non-config group defaults",id:"non-config-group-defaults",children:[],level:3}],u={toc:p};function c(e){var t=e.components,n=(0,i.A)(e,l);return(0,o.mdx)("wrapper",(0,a.A)({},u,n,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)(r.C,{to:"examples/tutorials/basic/your_first_hydra_app/5_defaults",mdxType:"ExampleGithubLink"}),(0,o.mdx)("p",null,"After office politics, you decide that you want to use MySQL by default.\nYou no longer want to type ",(0,o.mdx)("inlineCode",{parentName:"p"},"+db=mysql")," every time you run your application."),(0,o.mdx)("p",null,"You can add a ",(0,o.mdx)("strong",{parentName:"p"},"Default List")," to your config file.\nA ",(0,o.mdx)("strong",{parentName:"p"},"Defaults List")," is a list telling Hydra how to compose the final config object.\nBy convention, it is the first item in the config."),(0,o.mdx)("h3",{id:"config-group-defaults"},"Config group defaults"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - db: mysql\n")),(0,o.mdx)("p",null,"Remember to specify the ",(0,o.mdx)("inlineCode",{parentName:"p"},"config_name"),":"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'from omegaconf import DictConfig, OmegaConf\nimport hydra\n\n@hydra.main(version_base=None, config_path="conf", config_name="config")\ndef my_app(cfg: DictConfig) -> None:\n print(OmegaConf.to_yaml(cfg))\n\nif __name__ == "__main__":\n my_app()\n')),(0,o.mdx)("p",null,"When you run the updated application, MySQL is loaded by default."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py\ndb:\n driver: mysql\n pass: secret\n user: omry\n")),(0,o.mdx)("p",null,"You can have multiple items in the defaults list, e.g."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - db: mysql\n - db/mysql/engine: innodb\n")),(0,o.mdx)("p",null,"The defaults are ordered:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"If multiple configs define the same value, the last one wins. "),(0,o.mdx)("li",{parentName:"ul"},"If multiple configs contribute to the same dictionary, the result is the combined dictionary.")),(0,o.mdx)("h4",{id:"overriding-a-config-group-default"},"Overriding a config group default"),(0,o.mdx)("p",null,"You can still load PostgreSQL, and override individual values."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py db=postgresql db.timeout=20\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 20\n user: postgres_user\n")),(0,o.mdx)("p",null,"You can remove a default entry from the defaults list by prefixing it with ~:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py ~db\n{}\n")),(0,o.mdx)("h3",{id:"composition-order-of-primary-config"},"Composition order of primary config"),(0,o.mdx)("p",null,"Your primary config can contain both config values and a Defaults List.\nIn such cases, you should add the ",(0,o.mdx)("inlineCode",{parentName:"p"},"_self_")," keyword to your defaults list to specify the composition order of the config file relative to the items in the defaults list."),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"If you want your primary config to override the values of configs from the Defaults List, append ",(0,o.mdx)("inlineCode",{parentName:"li"},"_self_")," to the end of the Defaults List."),(0,o.mdx)("li",{parentName:"ul"},"If you want the configs from the Defaults List to override the values in your primary config, insert ",(0,o.mdx)("inlineCode",{parentName:"li"},"_self_")," as the first item in your Defaults List.")),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {3}',title:'"config.yaml"',"{3}":!0},"defaults:\n - db: mysql\n - _self_\n\ndb:\n user: root\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Result config: db.user from config.yaml" {4}',title:'"Result',"config:":!0,"db.user":!0,from:!0,'config.yaml"':!0,"{4}":!0},"db:\n driver: mysql # db/mysql.yaml\n pass: secret # db/mysql.yaml \n user: root # config.yaml\n\n\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {2}',title:'"config.yaml"',"{2}":!0},"defaults:\n - _self_\n - db: mysql\n\ndb:\n user: root\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Result config: All values from db/mysql" {4}',title:'"Result',"config:":!0,All:!0,values:!0,from:!0,'db/mysql"':!0,"{4}":!0},"db:\n driver: mysql # db/mysql.yaml\n pass: secret # db/mysql.yaml\n user: omry # db/mysql.yaml\n\n\n")))),(0,o.mdx)("p",null,"See ",(0,o.mdx)("a",{parentName:"p",href:"/docs/advanced/defaults_list#composition-order"},"Composition Order")," for more information."),(0,o.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,o.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,o.mdx)("h5",{parentName:"div"},(0,o.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,o.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,o.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"info")),(0,o.mdx)("div",{parentName:"div",className:"admonition-content"},(0,o.mdx)("p",{parentName:"div"},"The default composition order changed between Hydra 1.0 and Hydra 1.1."),(0,o.mdx)("ul",{parentName:"div"},(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("strong",{parentName:"li"},"Hydra 1.0"),": Configs from the defaults list are overriding the primary config"),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("strong",{parentName:"li"},"Hydra 1.1"),": A config is overriding the configs from the defaults list.")),(0,o.mdx)("p",{parentName:"div"},"To mitigate confusion, Hydra 1.1 issue a warning if the primary config contains both Default List and Config values, and ",(0,o.mdx)("inlineCode",{parentName:"p"},"_self_")," is not specified in the Defaults List.",(0,o.mdx)("br",{parentName:"p"}),"\n","The warning will disappear if you add ",(0,o.mdx)("inlineCode",{parentName:"p"},"_self_")," to the Defaults List based on the desired behavior."))),(0,o.mdx)("h3",{id:"non-config-group-defaults"},"Non-config group defaults"),(0,o.mdx)("p",null,"Sometimes a config file does not belong in any config group.\nYou can still load it by default. Here is an example for ",(0,o.mdx)("inlineCode",{parentName:"p"},"some_file.yaml"),"."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - some_file\n")),(0,o.mdx)("p",null,"Config files that are not part of a config group will always be loaded. They cannot be overridden.",(0,o.mdx)("br",{parentName:"p"}),"\n","Prefer using a config group."),(0,o.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,o.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,o.mdx)("h5",{parentName:"div"},(0,o.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,o.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,o.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"info")),(0,o.mdx)("div",{parentName:"div",className:"admonition-content"},(0,o.mdx)("p",{parentName:"div"},"For more information about the Defaults List see ",(0,o.mdx)("a",{parentName:"p",href:"/docs/advanced/defaults_list"},"Reference Manual/The Defaults List"),"."))))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1c50c1b8.ba53d91a.js b/assets/js/1c50c1b8.ba53d91a.js deleted file mode 100644 index c9c53f31ab..0000000000 --- a/assets/js/1c50c1b8.ba53d91a.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[7774],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>d,MDXProvider:()=>u,mdx:()=>g,useMDXComponents:()=>p,withMDXComponents:()=>m});var a=n(96540);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var d=a.createContext({}),m=function(e){return function(t){var n=p(t.components);return a.createElement(e,o({},t,{components:n}))}},p=function(e){var t=a.useContext(d),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},u=function(e){var t=p(e.components);return a.createElement(d.Provider,{value:t},e.children)},c={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},f=a.forwardRef((function(e,t){var n=e.components,i=e.mdxType,o=e.originalType,r=e.parentName,d=s(e,["components","mdxType","originalType","parentName"]),m=p(n),u=i,f=m["".concat(r,".").concat(u)]||m[u]||c[u]||o;return n?a.createElement(f,l(l({ref:t},d),{},{components:n})):a.createElement(f,l({ref:t},d))}));function g(e,t){var n=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var o=n.length,r=new Array(o);r[0]=f;var l={};for(var s in t)hasOwnProperty.call(t,s)&&(l[s]=t[s]);l.originalType=e,l.mdxType="string"==typeof e?e:i,r[1]=l;for(var d=2;d{n.d(t,{A:()=>s,C:()=>d});var a=n(58168),i=n(96540),o=n(75489),r=n(44586),l=n(74098);function s(e){return i.createElement(o.default,(0,a.A)({},e,{to:(t=e.to,s=(0,l.useActiveVersion)(),(0,r.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==s?void 0:s.name)?n:"current"]+t),target:"_blank"}));var t,n,s}function d(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return i.createElement(s,e,i.createElement("span",null,"\xa0"),i.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},33302:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>d,default:()=>c,frontMatter:()=>s,metadata:()=>m,toc:()=>p});var a=n(58168),i=n(98587),o=(n(96540),n(15680)),r=n(49595),l=["components"],s={id:"defaults",title:"Selecting default configs"},d=void 0,m={unversionedId:"tutorials/basic/your_first_app/defaults",id:"tutorials/basic/your_first_app/defaults",title:"Selecting default configs",description:"After office politics, you decide that you want to use MySQL by default.",source:"@site/docs/tutorials/basic/your_first_app/5_defaults.md",sourceDirName:"tutorials/basic/your_first_app",slug:"/tutorials/basic/your_first_app/defaults",permalink:"/docs/tutorials/basic/your_first_app/defaults",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/tutorials/basic/your_first_app/5_defaults.md",tags:[],version:"current",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:5,frontMatter:{id:"defaults",title:"Selecting default configs"},sidebar:"docs",previous:{title:"Grouping config files",permalink:"/docs/tutorials/basic/your_first_app/config_groups"},next:{title:"Putting it all together",permalink:"/docs/tutorials/basic/your_first_app/composition"}},p=[{value:"Config group defaults",id:"config-group-defaults",children:[{value:"Overriding a config group default",id:"overriding-a-config-group-default",children:[],level:4}],level:3},{value:"Composition order of primary config",id:"composition-order-of-primary-config",children:[],level:3},{value:"Non-config group defaults",id:"non-config-group-defaults",children:[],level:3}],u={toc:p};function c(e){var t=e.components,n=(0,i.A)(e,l);return(0,o.mdx)("wrapper",(0,a.A)({},u,n,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)(r.C,{to:"examples/tutorials/basic/your_first_hydra_app/5_defaults",mdxType:"ExampleGithubLink"}),(0,o.mdx)("p",null,"After office politics, you decide that you want to use MySQL by default.\nYou no longer want to type ",(0,o.mdx)("inlineCode",{parentName:"p"},"+db=mysql")," every time you run your application."),(0,o.mdx)("p",null,"You can add a ",(0,o.mdx)("strong",{parentName:"p"},"Default List")," to your config file.\nA ",(0,o.mdx)("strong",{parentName:"p"},"Defaults List")," is a list telling Hydra how to compose the final config object.\nBy convention, it is the first item in the config."),(0,o.mdx)("h3",{id:"config-group-defaults"},"Config group defaults"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - db: mysql\n")),(0,o.mdx)("p",null,"Remember to specify the ",(0,o.mdx)("inlineCode",{parentName:"p"},"config_name"),":"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'from omegaconf import DictConfig, OmegaConf\nimport hydra\n\n@hydra.main(version_base=None, config_path="conf", config_name="config")\ndef my_app(cfg: DictConfig) -> None:\n print(OmegaConf.to_yaml(cfg))\n\nif __name__ == "__main__":\n my_app()\n')),(0,o.mdx)("p",null,"When you run the updated application, MySQL is loaded by default."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py\ndb:\n driver: mysql\n pass: secret\n user: omry\n")),(0,o.mdx)("p",null,"You can have multiple items in the defaults list, e.g."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - db: mysql\n - db/mysql/engine: innodb\n")),(0,o.mdx)("p",null,"The defaults are ordered:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"If multiple configs define the same value, the last one wins. "),(0,o.mdx)("li",{parentName:"ul"},"If multiple configs contribute to the same dictionary, the result is the combined dictionary.")),(0,o.mdx)("h4",{id:"overriding-a-config-group-default"},"Overriding a config group default"),(0,o.mdx)("p",null,"You can still load PostgreSQL, and override individual values."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py db=postgresql db.timeout=20\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 20\n user: postgres_user\n")),(0,o.mdx)("p",null,"You can remove a default entry from the defaults list by prefixing it with ~:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py ~db\n{}\n")),(0,o.mdx)("h3",{id:"composition-order-of-primary-config"},"Composition order of primary config"),(0,o.mdx)("p",null,"Your primary config can contain both config values and a Defaults List.\nIn such cases, you should add the ",(0,o.mdx)("inlineCode",{parentName:"p"},"_self_")," keyword to your defaults list to specify the composition order of the config file relative to the items in the defaults list."),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"If you want your primary config to override the values of configs from the Defaults List, append ",(0,o.mdx)("inlineCode",{parentName:"li"},"_self_")," to the end of the Defaults List."),(0,o.mdx)("li",{parentName:"ul"},"If you want the configs from the Defaults List to override the values in your primary config, insert ",(0,o.mdx)("inlineCode",{parentName:"li"},"_self_")," as the first item in your Defaults List.")),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {3}',title:'"config.yaml"',"{3}":!0},"defaults:\n - db: mysql\n - _self_\n\ndb:\n user: root\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Result config: db.user from config.yaml" {4}',title:'"Result',"config:":!0,"db.user":!0,from:!0,'config.yaml"':!0,"{4}":!0},"db:\n driver: mysql # db/mysql.yaml\n pass: secret # db/mysql.yaml \n user: root # config.yaml\n\n\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {2}',title:'"config.yaml"',"{2}":!0},"defaults:\n - _self_\n - db: mysql\n\ndb:\n user: root\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Result config: All values from db/mysql" {4}',title:'"Result',"config:":!0,All:!0,values:!0,from:!0,'db/mysql"':!0,"{4}":!0},"db:\n driver: mysql # db/mysql.yaml\n pass: secret # db/mysql.yaml\n user: omry # db/mysql.yaml\n\n\n")))),(0,o.mdx)("p",null,"See ",(0,o.mdx)("a",{parentName:"p",href:"/docs/advanced/defaults_list#composition-order"},"Composition Order")," for more information."),(0,o.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,o.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,o.mdx)("h5",{parentName:"div"},(0,o.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,o.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,o.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"info")),(0,o.mdx)("div",{parentName:"div",className:"admonition-content"},(0,o.mdx)("p",{parentName:"div"},"The default composition order changed between Hydra 1.0 and Hydra 1.1."),(0,o.mdx)("ul",{parentName:"div"},(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("strong",{parentName:"li"},"Hydra 1.0"),": Configs from the defaults list are overriding the primary config"),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("strong",{parentName:"li"},"Hydra 1.1"),": A config is overriding the configs from the defaults list.")),(0,o.mdx)("p",{parentName:"div"},"To mitigate confusion, Hydra 1.1 issue a warning if the primary config contains both Default List and Config values, and ",(0,o.mdx)("inlineCode",{parentName:"p"},"_self_")," is not specified in the Defaults List.",(0,o.mdx)("br",{parentName:"p"}),"\n","The warning will disappear if you add ",(0,o.mdx)("inlineCode",{parentName:"p"},"_self_")," to the Defaults List based on the desired behavior."))),(0,o.mdx)("h3",{id:"non-config-group-defaults"},"Non-config group defaults"),(0,o.mdx)("p",null,"Sometimes a config file does not belong in any config group.\nYou can still load it by default. Here is an example for ",(0,o.mdx)("inlineCode",{parentName:"p"},"some_file.yaml"),"."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - some_file\n")),(0,o.mdx)("p",null,"Config files that are not part of a config group will always be loaded. They cannot be overridden.",(0,o.mdx)("br",{parentName:"p"}),"\n","Prefer using a config group."),(0,o.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,o.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,o.mdx)("h5",{parentName:"div"},(0,o.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,o.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,o.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"info")),(0,o.mdx)("div",{parentName:"div",className:"admonition-content"},(0,o.mdx)("p",{parentName:"div"},"For more information about the Defaults List see ",(0,o.mdx)("a",{parentName:"p",href:"/docs/advanced/defaults_list"},"Reference Manual/The Defaults List"),"."))))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1d831f5a.beb0df9c.js b/assets/js/1d831f5a.beb0df9c.js deleted file mode 100644 index a673d8571e..0000000000 --- a/assets/js/1d831f5a.beb0df9c.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[9404],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>s,MDXProvider:()=>d,mdx:()=>g,useMDXComponents:()=>p,withMDXComponents:()=>u});var r=t(96540);function a(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(a[t]=e[t]);return a}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(a[t]=e[t])}return a}var s=r.createContext({}),u=function(e){return function(n){var t=p(n.components);return r.createElement(e,i({},n,{components:t}))}},p=function(e){var n=r.useContext(s),t=n;return e&&(t="function"==typeof e?e(n):l(l({},n),e)),t},d=function(e){var n=p(e.components);return r.createElement(s.Provider,{value:n},e.children)},m={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},h=r.forwardRef((function(e,n){var t=e.components,a=e.mdxType,i=e.originalType,o=e.parentName,s=c(e,["components","mdxType","originalType","parentName"]),u=p(t),d=a,h=u["".concat(o,".").concat(d)]||u[d]||m[d]||i;return t?r.createElement(h,l(l({ref:n},s),{},{components:t})):r.createElement(h,l({ref:n},s))}));function g(e,n){var t=arguments,a=n&&n.mdxType;if("string"==typeof e||a){var i=t.length,o=new Array(i);o[0]=h;var l={};for(var c in n)hasOwnProperty.call(n,c)&&(l[c]=n[c]);l.originalType=e,l.mdxType="string"==typeof e?e:a,o[1]=l;for(var s=2;s{t.d(n,{A:()=>c,C:()=>s});var r=t(58168),a=t(96540),i=t(75489),o=t(44586),l=t(74098);function c(e){return a.createElement(i.default,(0,r.A)({},e,{to:(n=e.to,c=(0,l.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==c?void 0:c.name)?t:"current"]+n),target:"_blank"}));var n,t,c}function s(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return a.createElement(c,e,a.createElement("span",null,"\xa0"),a.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},88496:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>s,default:()=>m,frontMatter:()=>c,metadata:()=>u,toc:()=>p});var r=t(58168),a=t(98587),i=(t(96540),t(15680)),o=t(49595),l=["components"],c={id:"overview",title:"Plugins Overview",sidebar_label:"Plugins Overview"},s=void 0,u={unversionedId:"advanced/plugins/overview",id:"advanced/plugins/overview",title:"Plugins Overview",description:"Hydra can be extended via plugins.",source:"@site/docs/advanced/plugins/intro.md",sourceDirName:"advanced/plugins",slug:"/advanced/plugins/overview",permalink:"/docs/advanced/plugins/overview",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/advanced/plugins/intro.md",tags:[],version:"current",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"overview",title:"Plugins Overview",sidebar_label:"Plugins Overview"},sidebar:"docs",previous:{title:"Config Search Path",permalink:"/docs/advanced/search_path"},next:{title:"Plugin development",permalink:"/docs/advanced/plugins/develop"}},p=[{value:"Plugin types",id:"plugin-types",children:[{value:"Sweeper",id:"sweeper",children:[],level:3},{value:"Launcher",id:"launcher",children:[],level:3},{value:"SearchPathPlugin",id:"searchpathplugin",children:[],level:3},{value:"ConfigSource",id:"configsource",children:[],level:3}],level:2}],d={toc:p};function m(e){var n=e.components,t=(0,a.A)(e,l);return(0,i.mdx)("wrapper",(0,r.A)({},d,t,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Hydra can be extended via plugins.\nThe example plugins ",(0,i.mdx)(o.A,{to:"examples/plugins",mdxType:"GithubLink"},"here")," can help you get started with plugin development."),(0,i.mdx)("h2",{id:"plugin-types"},"Plugin types"),(0,i.mdx)("p",null,"Hydra has several plugin types:"),(0,i.mdx)("h3",{id:"sweeper"},"Sweeper"),(0,i.mdx)("p",null,"A sweeper is responsible for converting command line arguments list into multiple jobs.\nFor example, the basic built-in sweeper takes arguments like:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre"},"batch_size=128 optimizer=nesterov,adam learning_rate=0.01,0.1 \n")),(0,i.mdx)("p",null,"And creates 4 jobs with the following parameters:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre"},"batch_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")),(0,i.mdx)("h3",{id:"launcher"},"Launcher"),(0,i.mdx)("p",null,"Launchers 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. "),(0,i.mdx)("h3",{id:"searchpathplugin"},"SearchPathPlugin"),(0,i.mdx)("p",null,"A 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."),(0,i.mdx)("p",null,"SearchPathPlugin plugins are discovered automatically by Hydra and are being called to manipulate the search path before\nthe configuration is composed."),(0,i.mdx)("p",null,"Many other plugins also implement SearchPathPlugin to add their configuration to the config search path once they are installed. "),(0,i.mdx)("h3",{id:"configsource"},"ConfigSource"),(0,i.mdx)("p",null,"ConfigSource 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."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1d831f5a.e08c0ef0.js b/assets/js/1d831f5a.e08c0ef0.js new file mode 100644 index 0000000000..1778efda62 --- /dev/null +++ b/assets/js/1d831f5a.e08c0ef0.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[9404],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>s,MDXProvider:()=>d,mdx:()=>g,useMDXComponents:()=>p,withMDXComponents:()=>u});var r=t(96540);function a(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(a[t]=e[t]);return a}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(a[t]=e[t])}return a}var s=r.createContext({}),u=function(e){return function(n){var t=p(n.components);return r.createElement(e,i({},n,{components:t}))}},p=function(e){var n=r.useContext(s),t=n;return e&&(t="function"==typeof e?e(n):l(l({},n),e)),t},d=function(e){var n=p(e.components);return r.createElement(s.Provider,{value:n},e.children)},m={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},h=r.forwardRef((function(e,n){var t=e.components,a=e.mdxType,i=e.originalType,o=e.parentName,s=c(e,["components","mdxType","originalType","parentName"]),u=p(t),d=a,h=u["".concat(o,".").concat(d)]||u[d]||m[d]||i;return t?r.createElement(h,l(l({ref:n},s),{},{components:t})):r.createElement(h,l({ref:n},s))}));function g(e,n){var t=arguments,a=n&&n.mdxType;if("string"==typeof e||a){var i=t.length,o=new Array(i);o[0]=h;var l={};for(var c in n)hasOwnProperty.call(n,c)&&(l[c]=n[c]);l.originalType=e,l.mdxType="string"==typeof e?e:a,o[1]=l;for(var s=2;s{t.d(n,{A:()=>c,C:()=>s});var r=t(58168),a=t(96540),i=t(75489),o=t(44586),l=t(74098);function c(e){return a.createElement(i.default,(0,r.A)({},e,{to:(n=e.to,c=(0,l.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==c?void 0:c.name)?t:"current"]+n),target:"_blank"}));var n,t,c}function s(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return a.createElement(c,e,a.createElement("span",null,"\xa0"),a.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},88496:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>s,default:()=>m,frontMatter:()=>c,metadata:()=>u,toc:()=>p});var r=t(58168),a=t(98587),i=(t(96540),t(15680)),o=t(49595),l=["components"],c={id:"overview",title:"Plugins Overview",sidebar_label:"Plugins Overview"},s=void 0,u={unversionedId:"advanced/plugins/overview",id:"advanced/plugins/overview",title:"Plugins Overview",description:"Hydra can be extended via plugins.",source:"@site/docs/advanced/plugins/intro.md",sourceDirName:"advanced/plugins",slug:"/advanced/plugins/overview",permalink:"/docs/advanced/plugins/overview",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/advanced/plugins/intro.md",tags:[],version:"current",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"overview",title:"Plugins Overview",sidebar_label:"Plugins Overview"},sidebar:"docs",previous:{title:"Config Search Path",permalink:"/docs/advanced/search_path"},next:{title:"Plugin development",permalink:"/docs/advanced/plugins/develop"}},p=[{value:"Plugin types",id:"plugin-types",children:[{value:"Sweeper",id:"sweeper",children:[],level:3},{value:"Launcher",id:"launcher",children:[],level:3},{value:"SearchPathPlugin",id:"searchpathplugin",children:[],level:3},{value:"ConfigSource",id:"configsource",children:[],level:3}],level:2}],d={toc:p};function m(e){var n=e.components,t=(0,a.A)(e,l);return(0,i.mdx)("wrapper",(0,r.A)({},d,t,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Hydra can be extended via plugins.\nThe example plugins ",(0,i.mdx)(o.A,{to:"examples/plugins",mdxType:"GithubLink"},"here")," can help you get started with plugin development."),(0,i.mdx)("h2",{id:"plugin-types"},"Plugin types"),(0,i.mdx)("p",null,"Hydra has several plugin types:"),(0,i.mdx)("h3",{id:"sweeper"},"Sweeper"),(0,i.mdx)("p",null,"A sweeper is responsible for converting command line arguments list into multiple jobs.\nFor example, the basic built-in sweeper takes arguments like:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre"},"batch_size=128 optimizer=nesterov,adam learning_rate=0.01,0.1 \n")),(0,i.mdx)("p",null,"And creates 4 jobs with the following parameters:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre"},"batch_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")),(0,i.mdx)("h3",{id:"launcher"},"Launcher"),(0,i.mdx)("p",null,"Launchers 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. "),(0,i.mdx)("h3",{id:"searchpathplugin"},"SearchPathPlugin"),(0,i.mdx)("p",null,"A 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."),(0,i.mdx)("p",null,"SearchPathPlugin plugins are discovered automatically by Hydra and are being called to manipulate the search path before\nthe configuration is composed."),(0,i.mdx)("p",null,"Many other plugins also implement SearchPathPlugin to add their configuration to the config search path once they are installed. "),(0,i.mdx)("h3",{id:"configsource"},"ConfigSource"),(0,i.mdx)("p",null,"ConfigSource 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."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1d9190c2.0ed75b8b.js b/assets/js/1d9190c2.0ed75b8b.js deleted file mode 100644 index 3fad44471d..0000000000 --- a/assets/js/1d9190c2.0ed75b8b.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[7534],{15680:(e,r,n)=>{n.r(r),n.d(r,{MDXContext:()=>l,MDXProvider:()=>c,mdx:()=>f,useMDXComponents:()=>m,withMDXComponents:()=>u});var t=n(96540);function a(e,r,n){return r in e?Object.defineProperty(e,r,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[r]=n,e}function o(){return o=Object.assign||function(e){for(var r=1;r=0||(a[n]=e[n]);return a}(e,r);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(a[n]=e[n])}return a}var l=t.createContext({}),u=function(e){return function(r){var n=m(r.components);return t.createElement(e,o({},r,{components:n}))}},m=function(e){var r=t.useContext(l),n=r;return e&&(n="function"==typeof e?e(r):s(s({},r),e)),n},c=function(e){var r=m(e.components);return t.createElement(l.Provider,{value:r},e.children)},d={inlineCode:"code",wrapper:function(e){var r=e.children;return t.createElement(t.Fragment,{},r)}},h=t.forwardRef((function(e,r){var n=e.components,a=e.mdxType,o=e.originalType,i=e.parentName,l=p(e,["components","mdxType","originalType","parentName"]),u=m(n),c=a,h=u["".concat(i,".").concat(c)]||u[c]||d[c]||o;return n?t.createElement(h,s(s({ref:r},l),{},{components:n})):t.createElement(h,s({ref:r},l))}));function f(e,r){var n=arguments,a=r&&r.mdxType;if("string"==typeof e||a){var o=n.length,i=new Array(o);i[0]=h;var s={};for(var p in r)hasOwnProperty.call(r,p)&&(s[p]=r[p]);s.originalType=e,s.mdxType="string"==typeof e?e:a,i[1]=s;for(var l=2;l{n.r(r),n.d(r,{contentTitle:()=>p,default:()=>c,frontMatter:()=>s,metadata:()=>l,toc:()=>u});var t=n(58168),a=n(98587),o=(n(96540),n(15680)),i=["components"],s={id:"multi-run",title:"Multi-run",sidebar_label:"Multi-run"},p=void 0,l={unversionedId:"tutorials/basic/running_your_app/multi-run",id:"version-1.0/tutorials/basic/running_your_app/multi-run",title:"Multi-run",description:"Sometimes you want to run a parameter sweep.",source:"@site/versioned_docs/version-1.0/tutorials/basic/running_your_app/2_multirun.md",sourceDirName:"tutorials/basic/running_your_app",slug:"/tutorials/basic/running_your_app/multi-run",permalink:"/docs/1.0/tutorials/basic/running_your_app/multi-run",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.0/tutorials/basic/running_your_app/2_multirun.md",tags:[],version:"1.0",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:2,frontMatter:{id:"multi-run",title:"Multi-run",sidebar_label:"Multi-run"},sidebar:"version-1.0/docs",previous:{title:"Putting it all together",permalink:"/docs/1.0/tutorials/basic/your_first_app/composition"},next:{title:"Output/Working directory",permalink:"/docs/1.0/tutorials/basic/running_your_app/working_directory"}},u=[{value:"Sweeper",id:"sweeper",children:[],level:3},{value:"Launcher",id:"launcher",children:[],level:3}],m={toc:u};function c(e){var r=e.components,n=(0,a.A)(e,i);return(0,o.mdx)("wrapper",(0,t.A)({},m,n,{components:r,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"Sometimes you want to run a parameter sweep.\nA parameter sweep is a method of evaluating a function (or a program) with a pre-determined set of parameters.\nThe examples below will clarify what this means."),(0,o.mdx)("p",null,"To run a parameter sweep, use the ",(0,o.mdx)("inlineCode",{parentName:"p"},"--multirun")," (",(0,o.mdx)("inlineCode",{parentName:"p"},"-m"),") flag and pass a comma separated list for each\ndimension you want to sweep. "),(0,o.mdx)("p",null,"To run your program with the 3 different schemas in schema config group:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre"},"$ python my_app.py -m schema=warehouse,support,school\n")),(0,o.mdx)("p",null,"Here is sweep over the db types (mysql,postgresql) and the schemas (warehouse,support,school).\nOutput does not contain the configuration prints."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-text"}," $ python my_app.py schema=warehouse,support,school db=mysql,postgresql -m\n[2019-10-01 14:44:16,254] - Launching 6 jobs locally\n[2019-10-01 14:44:16,254] - Sweep output dir : multirun/2019-10-01/14-44-16\n[2019-10-01 14:44:16,254] - #0 : schema=warehouse db=mysql\n[2019-10-01 14:44:16,321] - #1 : schema=warehouse db=postgresql\n[2019-10-01 14:44:16,390] - #2 : schema=support db=mysql\n[2019-10-01 14:44:16,458] - #3 : schema=support db=postgresql\n[2019-10-01 14:44:16,527] - #4 : schema=school db=mysql\n[2019-10-01 14:44:16,602] - #5 : schema=school db=postgresql\n")),(0,o.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,o.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,o.mdx)("h5",{parentName:"div"},(0,o.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,o.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,o.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"info")),(0,o.mdx)("div",{parentName:"div",className:"admonition-content"},(0,o.mdx)("p",{parentName:"div"},"Hydra supports other kind of sweeps, for example a range sweep: ",(0,o.mdx)("strong",{parentName:"p"},"x=range(1,10)")," or a glob: ",(0,o.mdx)("strong",{parentName:"p"},"support=glob(*)"),".",(0,o.mdx)("br",{parentName:"p"}),"\n","See the ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.0/advanced/override_grammar/extended"},"Extended Override syntax")," for details."))),(0,o.mdx)("h3",{id:"sweeper"},"Sweeper"),(0,o.mdx)("p",null,"The sweeping logic is implemented by a simple sweeper that is built into Hydra.\nAdditional sweepers are available as plugins.\nFor example, the ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.0/plugins/ax_sweeper"},"Ax Sweeper")," can automatically find the best parameter combination!"),(0,o.mdx)("h3",{id:"launcher"},"Launcher"),(0,o.mdx)("p",null,"A Launcher is what runs your job. Hydra comes with a simple launcher that runs the jobs locally and serially.\nOther launchers are available as plugins for launching in parallel and on different clusters. For example, the ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.0/plugins/joblib_launcher"},"JobLib Launcher"),"\ncan execute the different parameter combinations in parallel on your local machine using multi-processing."))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1d9190c2.f42b49be.js b/assets/js/1d9190c2.f42b49be.js new file mode 100644 index 0000000000..c22755af6c --- /dev/null +++ b/assets/js/1d9190c2.f42b49be.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[7534],{15680:(e,r,t)=>{t.r(r),t.d(r,{MDXContext:()=>l,MDXProvider:()=>c,mdx:()=>f,useMDXComponents:()=>m,withMDXComponents:()=>u});var n=t(96540);function a(e,r,t){return r in e?Object.defineProperty(e,r,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[r]=t,e}function o(){return o=Object.assign||function(e){for(var r=1;r=0||(a[t]=e[t]);return a}(e,r);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(a[t]=e[t])}return a}var l=n.createContext({}),u=function(e){return function(r){var t=m(r.components);return n.createElement(e,o({},r,{components:t}))}},m=function(e){var r=n.useContext(l),t=r;return e&&(t="function"==typeof e?e(r):s(s({},r),e)),t},c=function(e){var r=m(e.components);return n.createElement(l.Provider,{value:r},e.children)},d={inlineCode:"code",wrapper:function(e){var r=e.children;return n.createElement(n.Fragment,{},r)}},h=n.forwardRef((function(e,r){var t=e.components,a=e.mdxType,o=e.originalType,i=e.parentName,l=p(e,["components","mdxType","originalType","parentName"]),u=m(t),c=a,h=u["".concat(i,".").concat(c)]||u[c]||d[c]||o;return t?n.createElement(h,s(s({ref:r},l),{},{components:t})):n.createElement(h,s({ref:r},l))}));function f(e,r){var t=arguments,a=r&&r.mdxType;if("string"==typeof e||a){var o=t.length,i=new Array(o);i[0]=h;var s={};for(var p in r)hasOwnProperty.call(r,p)&&(s[p]=r[p]);s.originalType=e,s.mdxType="string"==typeof e?e:a,i[1]=s;for(var l=2;l{t.r(r),t.d(r,{contentTitle:()=>p,default:()=>c,frontMatter:()=>s,metadata:()=>l,toc:()=>u});var n=t(58168),a=t(98587),o=(t(96540),t(15680)),i=["components"],s={id:"multi-run",title:"Multi-run",sidebar_label:"Multi-run"},p=void 0,l={unversionedId:"tutorials/basic/running_your_app/multi-run",id:"version-1.0/tutorials/basic/running_your_app/multi-run",title:"Multi-run",description:"Sometimes you want to run a parameter sweep.",source:"@site/versioned_docs/version-1.0/tutorials/basic/running_your_app/2_multirun.md",sourceDirName:"tutorials/basic/running_your_app",slug:"/tutorials/basic/running_your_app/multi-run",permalink:"/docs/1.0/tutorials/basic/running_your_app/multi-run",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.0/tutorials/basic/running_your_app/2_multirun.md",tags:[],version:"1.0",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:2,frontMatter:{id:"multi-run",title:"Multi-run",sidebar_label:"Multi-run"},sidebar:"version-1.0/docs",previous:{title:"Putting it all together",permalink:"/docs/1.0/tutorials/basic/your_first_app/composition"},next:{title:"Output/Working directory",permalink:"/docs/1.0/tutorials/basic/running_your_app/working_directory"}},u=[{value:"Sweeper",id:"sweeper",children:[],level:3},{value:"Launcher",id:"launcher",children:[],level:3}],m={toc:u};function c(e){var r=e.components,t=(0,a.A)(e,i);return(0,o.mdx)("wrapper",(0,n.A)({},m,t,{components:r,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"Sometimes you want to run a parameter sweep.\nA parameter sweep is a method of evaluating a function (or a program) with a pre-determined set of parameters.\nThe examples below will clarify what this means."),(0,o.mdx)("p",null,"To run a parameter sweep, use the ",(0,o.mdx)("inlineCode",{parentName:"p"},"--multirun")," (",(0,o.mdx)("inlineCode",{parentName:"p"},"-m"),") flag and pass a comma separated list for each\ndimension you want to sweep. "),(0,o.mdx)("p",null,"To run your program with the 3 different schemas in schema config group:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre"},"$ python my_app.py -m schema=warehouse,support,school\n")),(0,o.mdx)("p",null,"Here is sweep over the db types (mysql,postgresql) and the schemas (warehouse,support,school).\nOutput does not contain the configuration prints."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-text"}," $ python my_app.py schema=warehouse,support,school db=mysql,postgresql -m\n[2019-10-01 14:44:16,254] - Launching 6 jobs locally\n[2019-10-01 14:44:16,254] - Sweep output dir : multirun/2019-10-01/14-44-16\n[2019-10-01 14:44:16,254] - #0 : schema=warehouse db=mysql\n[2019-10-01 14:44:16,321] - #1 : schema=warehouse db=postgresql\n[2019-10-01 14:44:16,390] - #2 : schema=support db=mysql\n[2019-10-01 14:44:16,458] - #3 : schema=support db=postgresql\n[2019-10-01 14:44:16,527] - #4 : schema=school db=mysql\n[2019-10-01 14:44:16,602] - #5 : schema=school db=postgresql\n")),(0,o.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,o.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,o.mdx)("h5",{parentName:"div"},(0,o.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,o.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,o.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"info")),(0,o.mdx)("div",{parentName:"div",className:"admonition-content"},(0,o.mdx)("p",{parentName:"div"},"Hydra supports other kind of sweeps, for example a range sweep: ",(0,o.mdx)("strong",{parentName:"p"},"x=range(1,10)")," or a glob: ",(0,o.mdx)("strong",{parentName:"p"},"support=glob(*)"),".",(0,o.mdx)("br",{parentName:"p"}),"\n","See the ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.0/advanced/override_grammar/extended"},"Extended Override syntax")," for details."))),(0,o.mdx)("h3",{id:"sweeper"},"Sweeper"),(0,o.mdx)("p",null,"The sweeping logic is implemented by a simple sweeper that is built into Hydra.\nAdditional sweepers are available as plugins.\nFor example, the ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.0/plugins/ax_sweeper"},"Ax Sweeper")," can automatically find the best parameter combination!"),(0,o.mdx)("h3",{id:"launcher"},"Launcher"),(0,o.mdx)("p",null,"A Launcher is what runs your job. Hydra comes with a simple launcher that runs the jobs locally and serially.\nOther launchers are available as plugins for launching in parallel and on different clusters. For example, the ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.0/plugins/joblib_launcher"},"JobLib Launcher"),"\ncan execute the different parameter combinations in parallel on your local machine using multi-processing."))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1e1bc213.5fcb8afc.js b/assets/js/1e1bc213.5fcb8afc.js new file mode 100644 index 0000000000..1e99a6303b --- /dev/null +++ b/assets/js/1e1bc213.5fcb8afc.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[7303],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>s,MDXProvider:()=>m,mdx:()=>f,useMDXComponents:()=>u,withMDXComponents:()=>c});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var s=r.createContext({}),c=function(e){return function(t){var n=u(t.components);return r.createElement(e,a({},t,{components:n}))}},u=function(e){var t=r.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},m=function(e){var t=u(e.components);return r.createElement(s.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},p=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,s=g(e,["components","mdxType","originalType","parentName"]),c=u(n),m=o,p=c["".concat(i,".").concat(m)]||c[m]||d[m]||a;return n?r.createElement(p,l(l({ref:t},s),{},{components:n})):r.createElement(p,l({ref:t},s))}));function f(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=n.length,i=new Array(a);i[0]=p;var l={};for(var g in t)hasOwnProperty.call(t,g)&&(l[g]=t[g]);l.originalType=e,l.mdxType="string"==typeof e?e:o,i[1]=l;for(var s=2;s{n.d(t,{A:()=>g,C:()=>s});var r=n(58168),o=n(96540),a=n(75489),i=n(44586),l=n(74098);function g(e){return o.createElement(a.default,(0,r.A)({},e,{to:(t=e.to,g=(0,l.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==g?void 0:g.name)?n:"current"]+t),target:"_blank"}));var t,n,g}function s(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return o.createElement(g,e,o.createElement("span",null,"\xa0"),o.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},8883:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>s,default:()=>d,frontMatter:()=>g,metadata:()=>c,toc:()=>u});var r=n(58168),o=n(98587),a=(n(96540),n(15680)),i=n(49595),l=["components"],g={id:"logging",title:"Customizing logging",sidebar_label:"Customizing logging"},s=void 0,c={unversionedId:"configure_hydra/logging",id:"version-1.3/configure_hydra/logging",title:"Customizing logging",description:"Hydra is configuring Python standard logging library with the dictConfig method. You can learn more about it here.",source:"@site/versioned_docs/version-1.3/configure_hydra/logging.md",sourceDirName:"configure_hydra",slug:"/configure_hydra/logging",permalink:"/docs/1.3/configure_hydra/logging",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/configure_hydra/logging.md",tags:[],version:"1.3",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"logging",title:"Customizing logging",sidebar_label:"Customizing logging"},sidebar:"docs",previous:{title:"Job Configuration",permalink:"/docs/1.3/configure_hydra/job"},next:{title:"Customizing working directory pattern",permalink:"/docs/1.3/configure_hydra/workdir"}},u=[],m={toc:u};function d(e){var t=e.components,n=(0,o.A)(e,l);return(0,a.mdx)("wrapper",(0,r.A)({},m,n,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)(i.C,{text:"Example application",to:"examples/configure_hydra/logging",mdxType:"ExampleGithubLink"}),(0,a.mdx)("p",null,"Hydra is configuring Python standard logging library with the dictConfig method. You can learn more about it ",(0,a.mdx)("a",{parentName:"p",href:"https://docs.python.org/3/howto/logging.html"},"here"),".\nThere are two logging configurations, one for Hydra itself and one for the executed jobs."),(0,a.mdx)("p",null,"This example demonstrates how to customize the logging behavior of your Hydra app, by making the following changes\nto the default logging behavior:"),(0,a.mdx)("ul",null,(0,a.mdx)("li",{parentName:"ul"},"Outputs only to stdout (no log file)"),(0,a.mdx)("li",{parentName:"ul"},"Output a simpler log line pattern")),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - override hydra/job_logging: custom\n")),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="hydra/job_logging/custom.yaml"',title:'"hydra/job_logging/custom.yaml"'},"version: 1\nformatters:\n simple:\n format: '[%(levelname)s] - %(message)s'\nhandlers:\n console:\n class: logging.StreamHandler\n formatter: simple\n stream: ext://sys.stdout\nroot:\n handlers: [console]\n\ndisable_existing_loggers: false\n")),(0,a.mdx)("p",null,"This is what the default logging looks like:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre"},"$ python my_app.py hydra/job_logging=default\n[2020-08-24 13:43:26,761][__main__][INFO] - Info level message\n")),(0,a.mdx)("p",null,"And this is what the custom logging looks like:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text"},"$ python my_app.py \n[INFO] - Info level message\n")))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1e1bc213.789420d3.js b/assets/js/1e1bc213.789420d3.js deleted file mode 100644 index 669d879bfb..0000000000 --- a/assets/js/1e1bc213.789420d3.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[7303],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>s,MDXProvider:()=>m,mdx:()=>f,useMDXComponents:()=>u,withMDXComponents:()=>c});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var s=r.createContext({}),c=function(e){return function(t){var n=u(t.components);return r.createElement(e,a({},t,{components:n}))}},u=function(e){var t=r.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},m=function(e){var t=u(e.components);return r.createElement(s.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},p=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,s=g(e,["components","mdxType","originalType","parentName"]),c=u(n),m=o,p=c["".concat(i,".").concat(m)]||c[m]||d[m]||a;return n?r.createElement(p,l(l({ref:t},s),{},{components:n})):r.createElement(p,l({ref:t},s))}));function f(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=n.length,i=new Array(a);i[0]=p;var l={};for(var g in t)hasOwnProperty.call(t,g)&&(l[g]=t[g]);l.originalType=e,l.mdxType="string"==typeof e?e:o,i[1]=l;for(var s=2;s{n.d(t,{A:()=>g,C:()=>s});var r=n(58168),o=n(96540),a=n(75489),i=n(44586),l=n(74098);function g(e){return o.createElement(a.default,(0,r.A)({},e,{to:(t=e.to,g=(0,l.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==g?void 0:g.name)?n:"current"]+t),target:"_blank"}));var t,n,g}function s(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return o.createElement(g,e,o.createElement("span",null,"\xa0"),o.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},8883:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>s,default:()=>d,frontMatter:()=>g,metadata:()=>c,toc:()=>u});var r=n(58168),o=n(98587),a=(n(96540),n(15680)),i=n(49595),l=["components"],g={id:"logging",title:"Customizing logging",sidebar_label:"Customizing logging"},s=void 0,c={unversionedId:"configure_hydra/logging",id:"version-1.3/configure_hydra/logging",title:"Customizing logging",description:"Hydra is configuring Python standard logging library with the dictConfig method. You can learn more about it here.",source:"@site/versioned_docs/version-1.3/configure_hydra/logging.md",sourceDirName:"configure_hydra",slug:"/configure_hydra/logging",permalink:"/docs/1.3/configure_hydra/logging",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/configure_hydra/logging.md",tags:[],version:"1.3",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"logging",title:"Customizing logging",sidebar_label:"Customizing logging"},sidebar:"docs",previous:{title:"Job Configuration",permalink:"/docs/1.3/configure_hydra/job"},next:{title:"Customizing working directory pattern",permalink:"/docs/1.3/configure_hydra/workdir"}},u=[],m={toc:u};function d(e){var t=e.components,n=(0,o.A)(e,l);return(0,a.mdx)("wrapper",(0,r.A)({},m,n,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)(i.C,{text:"Example application",to:"examples/configure_hydra/logging",mdxType:"ExampleGithubLink"}),(0,a.mdx)("p",null,"Hydra is configuring Python standard logging library with the dictConfig method. You can learn more about it ",(0,a.mdx)("a",{parentName:"p",href:"https://docs.python.org/3/howto/logging.html"},"here"),".\nThere are two logging configurations, one for Hydra itself and one for the executed jobs."),(0,a.mdx)("p",null,"This example demonstrates how to customize the logging behavior of your Hydra app, by making the following changes\nto the default logging behavior:"),(0,a.mdx)("ul",null,(0,a.mdx)("li",{parentName:"ul"},"Outputs only to stdout (no log file)"),(0,a.mdx)("li",{parentName:"ul"},"Output a simpler log line pattern")),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - override hydra/job_logging: custom\n")),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="hydra/job_logging/custom.yaml"',title:'"hydra/job_logging/custom.yaml"'},"version: 1\nformatters:\n simple:\n format: '[%(levelname)s] - %(message)s'\nhandlers:\n console:\n class: logging.StreamHandler\n formatter: simple\n stream: ext://sys.stdout\nroot:\n handlers: [console]\n\ndisable_existing_loggers: false\n")),(0,a.mdx)("p",null,"This is what the default logging looks like:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre"},"$ python my_app.py hydra/job_logging=default\n[2020-08-24 13:43:26,761][__main__][INFO] - Info level message\n")),(0,a.mdx)("p",null,"And this is what the custom logging looks like:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text"},"$ python my_app.py \n[INFO] - Info level message\n")))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1e2eb92a.52797a10.js b/assets/js/1e2eb92a.52797a10.js new file mode 100644 index 0000000000..d404613e55 --- /dev/null +++ b/assets/js/1e2eb92a.52797a10.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[290],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>m,MDXProvider:()=>u,mdx:()=>h,useMDXComponents:()=>s,withMDXComponents:()=>d});var t=a(96540);function r(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(r[a]=e[a]);return r}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(r[a]=e[a])}return r}var m=t.createContext({}),d=function(e){return function(n){var a=s(n.components);return t.createElement(e,i({},n,{components:a}))}},s=function(e){var n=t.useContext(m),a=n;return e&&(a="function"==typeof e?e(n):p(p({},n),e)),a},u=function(e){var n=s(e.components);return t.createElement(m.Provider,{value:n},e.children)},c={inlineCode:"code",wrapper:function(e){var n=e.children;return t.createElement(t.Fragment,{},n)}},x=t.forwardRef((function(e,n){var a=e.components,r=e.mdxType,i=e.originalType,o=e.parentName,m=l(e,["components","mdxType","originalType","parentName"]),d=s(a),u=r,x=d["".concat(o,".").concat(u)]||d[u]||c[u]||i;return a?t.createElement(x,p(p({ref:n},m),{},{components:a})):t.createElement(x,p({ref:n},m))}));function h(e,n){var a=arguments,r=n&&n.mdxType;if("string"==typeof e||r){var i=a.length,o=new Array(i);o[0]=x;var p={};for(var l in n)hasOwnProperty.call(n,l)&&(p[l]=n[l]);p.originalType=e,p.mdxType="string"==typeof e?e:r,o[1]=p;for(var m=2;m{a.d(n,{A:()=>l,C:()=>m});var t=a(58168),r=a(96540),i=a(75489),o=a(44586),p=a(74098);function l(e){return r.createElement(i.default,(0,t.A)({},e,{to:(n=e.to,l=(0,p.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(a=null==l?void 0:l.name)?a:"current"]+n),target:"_blank"}));var n,a,l}function m(e){var n,a=null!=(n=e.text)?n:"Example (Click Here)";return r.createElement(l,e,r.createElement("span",null,"\xa0"),r.createElement("img",{src:"https://img.shields.io/badge/-"+a+"-informational",alt:"Example (Click Here)"}))}},2232:(e,n,a)=>{a.r(n),a.d(n,{contentTitle:()=>d,default:()=>h,frontMatter:()=>m,metadata:()=>s,toc:()=>u});var t,r=a(58168),i=a(98587),o=(a(96540),a(15680)),p=a(49595),l=["components"],m={id:"ax_sweeper",title:"Ax Sweeper plugin",sidebar_label:"Ax Sweeper plugin"},d=void 0,s={unversionedId:"plugins/ax_sweeper",id:"plugins/ax_sweeper",title:"Ax Sweeper plugin",description:"PyPI",source:"@site/docs/plugins/ax_sweeper.md",sourceDirName:"plugins",slug:"/plugins/ax_sweeper",permalink:"/docs/plugins/ax_sweeper",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/plugins/ax_sweeper.md",tags:[],version:"current",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"ax_sweeper",title:"Ax Sweeper plugin",sidebar_label:"Ax Sweeper plugin"},sidebar:"docs",previous:{title:"Submitit Launcher plugin",permalink:"/docs/plugins/submitit_launcher"},next:{title:"Nevergrad Sweeper plugin",permalink:"/docs/plugins/nevergrad_sweeper"}},u=[{value:"Installation",id:"installation",children:[],level:3},{value:"Usage",id:"usage",children:[],level:3}],c=(t="GithubLink",function(e){return console.warn("Component "+t+" was not imported, exported, or provided by MDXProvider as global scope"),(0,o.mdx)("div",e)}),x={toc:u};function h(e){var n=e.components,a=(0,i.A)(e,l);return(0,o.mdx)("wrapper",(0,r.A)({},x,a,{components:n,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,(0,o.mdx)("a",{parentName:"p",href:"https://img.shields.io/pypi/v/hydra-ax-sweeper"},(0,o.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/v/hydra-ax-sweeper",alt:"PyPI"})),"\n",(0,o.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/l/hydra-ax-sweeper",alt:"PyPI - License"}),"\n",(0,o.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/pyversions/hydra-ax-sweeper",alt:"PyPI - Python Version"}),"\n",(0,o.mdx)("a",{parentName:"p",href:"https://pypistats.org/packages/hydra-ax-sweeper"},(0,o.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/dm/hydra-ax-sweeper.svg",alt:"PyPI - Downloads"})),(0,o.mdx)(p.C,{text:"Example application",to:"plugins/hydra_ax_sweeper/example",mdxType:"ExampleGithubLink"}),(0,o.mdx)(p.C,{text:"Plugin source",to:"plugins/hydra_ax_sweeper",mdxType:"ExampleGithubLink"})),(0,o.mdx)("p",null,"This plugin provides a mechanism for Hydra applications to use the ",(0,o.mdx)("a",{parentName:"p",href:"https://ax.dev/"},"Adaptive Experimentation Platform, aka Ax"),". Ax can optimize any experiment - machine learning experiments, A/B tests, and simulations."),(0,o.mdx)("h3",{id:"installation"},"Installation"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-commandline"},"pip install hydra-ax-sweeper --upgrade\n")),(0,o.mdx)("h3",{id:"usage"},"Usage"),(0,o.mdx)("p",null,"Once installed, add ",(0,o.mdx)("inlineCode",{parentName:"p"},"hydra/sweeper=ax")," to your command line. Alternatively, override ",(0,o.mdx)("inlineCode",{parentName:"p"},"hydra/sweeper")," in your config:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - override hydra/sweeper: ax\n")),(0,o.mdx)("p",null,"We include an example of how to use this plugin. The file ",(0,o.mdx)(c,{to:"plugins/hydra_ax_sweeper/example/banana.py",mdxType:"GithubLink"},"example/banana.py"),"\nimplements the ",(0,o.mdx)("a",{parentName:"p",href:"https://en.wikipedia.org/wiki/Rosenbrock_function"},"Rosenbrock function (aka Banana function)"),".\nThe return value of the function should be the value that we want to optimize."),(0,o.mdx)("p",null,"To compute the best parameters for the Banana function, clone the code and run the following command in the ",(0,o.mdx)("inlineCode",{parentName:"p"},"plugins/hydra_ax_sweeper")," directory:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre"},"python example/banana.py -m 'banana.x=int(interval(-5, 5))' 'banana.y=interval(-5, 10.1)'\n")),(0,o.mdx)("p",null,"The output of a run looks like:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre"},"[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")),(0,o.mdx)("p",null,"In this example, we set the range of ",(0,o.mdx)("inlineCode",{parentName:"p"},"x")," parameter as an integer in the interval ",(0,o.mdx)("inlineCode",{parentName:"p"},"[-5, 5]")," and the range of ",(0,o.mdx)("inlineCode",{parentName:"p"},"y")," parameter as a float in the interval ",(0,o.mdx)("inlineCode",{parentName:"p"},"[-5, 10.1]"),". Note that in the case of ",(0,o.mdx)("inlineCode",{parentName:"p"},"x"),", we used ",(0,o.mdx)("inlineCode",{parentName:"p"},"int(interval(...))")," and hence only integers are sampled. In the case of ",(0,o.mdx)("inlineCode",{parentName:"p"},"y"),", we used ",(0,o.mdx)("inlineCode",{parentName:"p"},"interval(...)")," which refers to a floating-point interval. Other supported formats are fixed parameters (e.g.",(0,o.mdx)("inlineCode",{parentName:"p"}," banana.x=5.0"),"), choice parameters (eg ",(0,o.mdx)("inlineCode",{parentName:"p"},"banana.x=choice(1,2,3)"),") and range (eg ",(0,o.mdx)("inlineCode",{parentName:"p"},"banana.x=range(1, 10)"),"). Note that ",(0,o.mdx)("inlineCode",{parentName:"p"},"interval"),", ",(0,o.mdx)("inlineCode",{parentName:"p"},"choice")," etc. are functions provided by Hydra, and you can read more about them ",(0,o.mdx)("a",{parentName:"p",href:"/docs/advanced/override_grammar/extended"},"here"),". An important thing to remember is, use ",(0,o.mdx)("a",{parentName:"p",href:"/docs/advanced/override_grammar/extended#interval-sweep"},(0,o.mdx)("inlineCode",{parentName:"a"},"interval"))," when we want Ax to sample values from an interval. ",(0,o.mdx)("a",{parentName:"p",href:"https://ax.dev/api/ax.html#ax.RangeParameter"},(0,o.mdx)("inlineCode",{parentName:"a"},"RangeParameter"))," in Ax is equivalent to ",(0,o.mdx)("inlineCode",{parentName:"p"},"interval")," in Hydra. Remember to use ",(0,o.mdx)("inlineCode",{parentName:"p"},"int(interval(...))")," if you want to sample only integer points from the interval. ",(0,o.mdx)("a",{parentName:"p",href:"/docs/advanced/override_grammar/extended#range-sweep"},(0,o.mdx)("inlineCode",{parentName:"a"},"range"))," can be used as an alternate way of specifying choice parameters. For example ",(0,o.mdx)("inlineCode",{parentName:"p"},"python example/banana.py -m banana.x=choice(1, 2, 3, 4)")," is equivalent to ",(0,o.mdx)("inlineCode",{parentName:"p"},"python example/banana.py -m banana.x=range(1, 5)"),"."),(0,o.mdx)("p",null,"The values of the ",(0,o.mdx)("inlineCode",{parentName:"p"},"x")," and ",(0,o.mdx)("inlineCode",{parentName:"p"},"y")," parameters can also be set using the config file ",(0,o.mdx)("inlineCode",{parentName:"p"},"plugins/hydra_ax_sweeper/example/conf/config.yaml"),". For instance, the configuration corresponding to the commandline arguments is as follows:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre"},"banana.x:\n type: range\n bounds: [-5, 5]\n\nbanana.y:\n type: range\n bounds: [-5, 10.1]\n")),(0,o.mdx)("p",null,"To sample in log space, you can tag the commandline override with ",(0,o.mdx)("inlineCode",{parentName:"p"},"log"),". E.g. ",(0,o.mdx)("inlineCode",{parentName:"p"},"python example/banana.py -m banana.x=tag(log, interval(1, 1000))"),". You can set ",(0,o.mdx)("inlineCode",{parentName:"p"},"log_scale: true")," in the input config to achieve the same."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre"},"banana.z:\n type: range\n bounds: [1, 100]\n log_scale: true\n")),(0,o.mdx)("p",null,"In general, the plugin supports setting all the Ax supported ",(0,o.mdx)("a",{parentName:"p",href:"https://ax.dev/api/core.html?highlight=range#module-ax.core.parameter"},"Parameters")," in the config. According to the ",(0,o.mdx)("a",{parentName:"p",href:"https://ax.dev/api/service.html#ax.service.ax_client.AxClient.create_experiment"},"Ax documentation"),", the required elements in the config are:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"name")," - Name of the parameter. It is of type string."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"type")," - Type of the parameter. It can take the following values: ",(0,o.mdx)("inlineCode",{parentName:"li"},"range"),", ",(0,o.mdx)("inlineCode",{parentName:"li"},"fixed"),", or ",(0,o.mdx)("inlineCode",{parentName:"li"},"choice"),"."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"bounds")," - Required only for the ",(0,o.mdx)("inlineCode",{parentName:"li"},"range")," parameters. It should be a list of two values, with the lower bound first."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"values")," - Required only for the ",(0,o.mdx)("inlineCode",{parentName:"li"},"choice")," parameters. It should be a list of values."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"value")," - Required only for the ",(0,o.mdx)("inlineCode",{parentName:"li"},"fixed")," parameters. It should be a single value.")),(0,o.mdx)("p",null,"Note that if you want to sample integers in the range ",(0,o.mdx)("inlineCode",{parentName:"p"},"-5")," to ",(0,o.mdx)("inlineCode",{parentName:"p"},"5"),", you need to specify the range as ",(0,o.mdx)("inlineCode",{parentName:"p"},"int(interval(-5, 5))")," (in the command line) or ",(0,o.mdx)("inlineCode",{parentName:"p"},"[-5, 5]")," (in config). If you want to sample floats in range ",(0,o.mdx)("inlineCode",{parentName:"p"},"-5")," to ",(0,o.mdx)("inlineCode",{parentName:"p"},"5"),", you need to specify the range as ",(0,o.mdx)("inlineCode",{parentName:"p"},"interval(-5, 5)")," (in the command line) or ",(0,o.mdx)("inlineCode",{parentName:"p"},"[-5.0, 5.0]")," (in config)."),(0,o.mdx)("p",null,"The Ax Sweeper assumes the optimized function is a noisy function with unknown measurement uncertainty.\nThis can be changed by overriding the ",(0,o.mdx)("inlineCode",{parentName:"p"},"is_noisy")," parameter to False, which specifies that each measurement is exact, i.e., each measurement has a measurement uncertainty of zero."),(0,o.mdx)("p",null,"If measurement uncertainty is known or can be estimated (e.g., via a heuristic or via the ",(0,o.mdx)("a",{parentName:"p",href:"https://en.wikipedia.org/wiki/Standard_error"},"standard error of the mean")," of repeated measurements), the measurement function can return the tuple ",(0,o.mdx)("inlineCode",{parentName:"p"},"(measurement_value, measurement_uncertainty)")," instead of a scalar value."),(0,o.mdx)("p",null,"The 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:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python your_app.py hydra/sweeper=ax --cfg hydra -p hydra.sweeper"',title:'"$',python:!0,"your_app.py":!0,"hydra/sweeper":"ax","--cfg":!0,hydra:!0,"-p":!0,'hydra.sweeper"':!0},"# @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")),(0,o.mdx)("p",null,"There are several standard approaches for configuring plugins. Check ",(0,o.mdx)("a",{parentName:"p",href:"/docs/patterns/configuring_plugins"},"this page")," for more information."))}h.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1e2eb92a.c8dd35f5.js b/assets/js/1e2eb92a.c8dd35f5.js deleted file mode 100644 index 4247fd9b72..0000000000 --- a/assets/js/1e2eb92a.c8dd35f5.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[290],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>m,MDXProvider:()=>u,mdx:()=>h,useMDXComponents:()=>s,withMDXComponents:()=>d});var t=a(96540);function r(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(r[a]=e[a]);return r}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(r[a]=e[a])}return r}var m=t.createContext({}),d=function(e){return function(n){var a=s(n.components);return t.createElement(e,i({},n,{components:a}))}},s=function(e){var n=t.useContext(m),a=n;return e&&(a="function"==typeof e?e(n):p(p({},n),e)),a},u=function(e){var n=s(e.components);return t.createElement(m.Provider,{value:n},e.children)},c={inlineCode:"code",wrapper:function(e){var n=e.children;return t.createElement(t.Fragment,{},n)}},x=t.forwardRef((function(e,n){var a=e.components,r=e.mdxType,i=e.originalType,o=e.parentName,m=l(e,["components","mdxType","originalType","parentName"]),d=s(a),u=r,x=d["".concat(o,".").concat(u)]||d[u]||c[u]||i;return a?t.createElement(x,p(p({ref:n},m),{},{components:a})):t.createElement(x,p({ref:n},m))}));function h(e,n){var a=arguments,r=n&&n.mdxType;if("string"==typeof e||r){var i=a.length,o=new Array(i);o[0]=x;var p={};for(var l in n)hasOwnProperty.call(n,l)&&(p[l]=n[l]);p.originalType=e,p.mdxType="string"==typeof e?e:r,o[1]=p;for(var m=2;m{a.d(n,{A:()=>l,C:()=>m});var t=a(58168),r=a(96540),i=a(75489),o=a(44586),p=a(74098);function l(e){return r.createElement(i.default,(0,t.A)({},e,{to:(n=e.to,l=(0,p.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(a=null==l?void 0:l.name)?a:"current"]+n),target:"_blank"}));var n,a,l}function m(e){var n,a=null!=(n=e.text)?n:"Example (Click Here)";return r.createElement(l,e,r.createElement("span",null,"\xa0"),r.createElement("img",{src:"https://img.shields.io/badge/-"+a+"-informational",alt:"Example (Click Here)"}))}},2232:(e,n,a)=>{a.r(n),a.d(n,{contentTitle:()=>d,default:()=>h,frontMatter:()=>m,metadata:()=>s,toc:()=>u});var t,r=a(58168),i=a(98587),o=(a(96540),a(15680)),p=a(49595),l=["components"],m={id:"ax_sweeper",title:"Ax Sweeper plugin",sidebar_label:"Ax Sweeper plugin"},d=void 0,s={unversionedId:"plugins/ax_sweeper",id:"plugins/ax_sweeper",title:"Ax Sweeper plugin",description:"PyPI",source:"@site/docs/plugins/ax_sweeper.md",sourceDirName:"plugins",slug:"/plugins/ax_sweeper",permalink:"/docs/plugins/ax_sweeper",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/plugins/ax_sweeper.md",tags:[],version:"current",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"ax_sweeper",title:"Ax Sweeper plugin",sidebar_label:"Ax Sweeper plugin"},sidebar:"docs",previous:{title:"Submitit Launcher plugin",permalink:"/docs/plugins/submitit_launcher"},next:{title:"Nevergrad Sweeper plugin",permalink:"/docs/plugins/nevergrad_sweeper"}},u=[{value:"Installation",id:"installation",children:[],level:3},{value:"Usage",id:"usage",children:[],level:3}],c=(t="GithubLink",function(e){return console.warn("Component "+t+" was not imported, exported, or provided by MDXProvider as global scope"),(0,o.mdx)("div",e)}),x={toc:u};function h(e){var n=e.components,a=(0,i.A)(e,l);return(0,o.mdx)("wrapper",(0,r.A)({},x,a,{components:n,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,(0,o.mdx)("a",{parentName:"p",href:"https://img.shields.io/pypi/v/hydra-ax-sweeper"},(0,o.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/v/hydra-ax-sweeper",alt:"PyPI"})),"\n",(0,o.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/l/hydra-ax-sweeper",alt:"PyPI - License"}),"\n",(0,o.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/pyversions/hydra-ax-sweeper",alt:"PyPI - Python Version"}),"\n",(0,o.mdx)("a",{parentName:"p",href:"https://pypistats.org/packages/hydra-ax-sweeper"},(0,o.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/dm/hydra-ax-sweeper.svg",alt:"PyPI - Downloads"})),(0,o.mdx)(p.C,{text:"Example application",to:"plugins/hydra_ax_sweeper/example",mdxType:"ExampleGithubLink"}),(0,o.mdx)(p.C,{text:"Plugin source",to:"plugins/hydra_ax_sweeper",mdxType:"ExampleGithubLink"})),(0,o.mdx)("p",null,"This plugin provides a mechanism for Hydra applications to use the ",(0,o.mdx)("a",{parentName:"p",href:"https://ax.dev/"},"Adaptive Experimentation Platform, aka Ax"),". Ax can optimize any experiment - machine learning experiments, A/B tests, and simulations."),(0,o.mdx)("h3",{id:"installation"},"Installation"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-commandline"},"pip install hydra-ax-sweeper --upgrade\n")),(0,o.mdx)("h3",{id:"usage"},"Usage"),(0,o.mdx)("p",null,"Once installed, add ",(0,o.mdx)("inlineCode",{parentName:"p"},"hydra/sweeper=ax")," to your command line. Alternatively, override ",(0,o.mdx)("inlineCode",{parentName:"p"},"hydra/sweeper")," in your config:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - override hydra/sweeper: ax\n")),(0,o.mdx)("p",null,"We include an example of how to use this plugin. The file ",(0,o.mdx)(c,{to:"plugins/hydra_ax_sweeper/example/banana.py",mdxType:"GithubLink"},"example/banana.py"),"\nimplements the ",(0,o.mdx)("a",{parentName:"p",href:"https://en.wikipedia.org/wiki/Rosenbrock_function"},"Rosenbrock function (aka Banana function)"),".\nThe return value of the function should be the value that we want to optimize."),(0,o.mdx)("p",null,"To compute the best parameters for the Banana function, clone the code and run the following command in the ",(0,o.mdx)("inlineCode",{parentName:"p"},"plugins/hydra_ax_sweeper")," directory:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre"},"python example/banana.py -m 'banana.x=int(interval(-5, 5))' 'banana.y=interval(-5, 10.1)'\n")),(0,o.mdx)("p",null,"The output of a run looks like:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre"},"[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")),(0,o.mdx)("p",null,"In this example, we set the range of ",(0,o.mdx)("inlineCode",{parentName:"p"},"x")," parameter as an integer in the interval ",(0,o.mdx)("inlineCode",{parentName:"p"},"[-5, 5]")," and the range of ",(0,o.mdx)("inlineCode",{parentName:"p"},"y")," parameter as a float in the interval ",(0,o.mdx)("inlineCode",{parentName:"p"},"[-5, 10.1]"),". Note that in the case of ",(0,o.mdx)("inlineCode",{parentName:"p"},"x"),", we used ",(0,o.mdx)("inlineCode",{parentName:"p"},"int(interval(...))")," and hence only integers are sampled. In the case of ",(0,o.mdx)("inlineCode",{parentName:"p"},"y"),", we used ",(0,o.mdx)("inlineCode",{parentName:"p"},"interval(...)")," which refers to a floating-point interval. Other supported formats are fixed parameters (e.g.",(0,o.mdx)("inlineCode",{parentName:"p"}," banana.x=5.0"),"), choice parameters (eg ",(0,o.mdx)("inlineCode",{parentName:"p"},"banana.x=choice(1,2,3)"),") and range (eg ",(0,o.mdx)("inlineCode",{parentName:"p"},"banana.x=range(1, 10)"),"). Note that ",(0,o.mdx)("inlineCode",{parentName:"p"},"interval"),", ",(0,o.mdx)("inlineCode",{parentName:"p"},"choice")," etc. are functions provided by Hydra, and you can read more about them ",(0,o.mdx)("a",{parentName:"p",href:"/docs/advanced/override_grammar/extended"},"here"),". An important thing to remember is, use ",(0,o.mdx)("a",{parentName:"p",href:"/docs/advanced/override_grammar/extended#interval-sweep"},(0,o.mdx)("inlineCode",{parentName:"a"},"interval"))," when we want Ax to sample values from an interval. ",(0,o.mdx)("a",{parentName:"p",href:"https://ax.dev/api/ax.html#ax.RangeParameter"},(0,o.mdx)("inlineCode",{parentName:"a"},"RangeParameter"))," in Ax is equivalent to ",(0,o.mdx)("inlineCode",{parentName:"p"},"interval")," in Hydra. Remember to use ",(0,o.mdx)("inlineCode",{parentName:"p"},"int(interval(...))")," if you want to sample only integer points from the interval. ",(0,o.mdx)("a",{parentName:"p",href:"/docs/advanced/override_grammar/extended#range-sweep"},(0,o.mdx)("inlineCode",{parentName:"a"},"range"))," can be used as an alternate way of specifying choice parameters. For example ",(0,o.mdx)("inlineCode",{parentName:"p"},"python example/banana.py -m banana.x=choice(1, 2, 3, 4)")," is equivalent to ",(0,o.mdx)("inlineCode",{parentName:"p"},"python example/banana.py -m banana.x=range(1, 5)"),"."),(0,o.mdx)("p",null,"The values of the ",(0,o.mdx)("inlineCode",{parentName:"p"},"x")," and ",(0,o.mdx)("inlineCode",{parentName:"p"},"y")," parameters can also be set using the config file ",(0,o.mdx)("inlineCode",{parentName:"p"},"plugins/hydra_ax_sweeper/example/conf/config.yaml"),". For instance, the configuration corresponding to the commandline arguments is as follows:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre"},"banana.x:\n type: range\n bounds: [-5, 5]\n\nbanana.y:\n type: range\n bounds: [-5, 10.1]\n")),(0,o.mdx)("p",null,"To sample in log space, you can tag the commandline override with ",(0,o.mdx)("inlineCode",{parentName:"p"},"log"),". E.g. ",(0,o.mdx)("inlineCode",{parentName:"p"},"python example/banana.py -m banana.x=tag(log, interval(1, 1000))"),". You can set ",(0,o.mdx)("inlineCode",{parentName:"p"},"log_scale: true")," in the input config to achieve the same."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre"},"banana.z:\n type: range\n bounds: [1, 100]\n log_scale: true\n")),(0,o.mdx)("p",null,"In general, the plugin supports setting all the Ax supported ",(0,o.mdx)("a",{parentName:"p",href:"https://ax.dev/api/core.html?highlight=range#module-ax.core.parameter"},"Parameters")," in the config. According to the ",(0,o.mdx)("a",{parentName:"p",href:"https://ax.dev/api/service.html#ax.service.ax_client.AxClient.create_experiment"},"Ax documentation"),", the required elements in the config are:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"name")," - Name of the parameter. It is of type string."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"type")," - Type of the parameter. It can take the following values: ",(0,o.mdx)("inlineCode",{parentName:"li"},"range"),", ",(0,o.mdx)("inlineCode",{parentName:"li"},"fixed"),", or ",(0,o.mdx)("inlineCode",{parentName:"li"},"choice"),"."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"bounds")," - Required only for the ",(0,o.mdx)("inlineCode",{parentName:"li"},"range")," parameters. It should be a list of two values, with the lower bound first."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"values")," - Required only for the ",(0,o.mdx)("inlineCode",{parentName:"li"},"choice")," parameters. It should be a list of values."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"value")," - Required only for the ",(0,o.mdx)("inlineCode",{parentName:"li"},"fixed")," parameters. It should be a single value.")),(0,o.mdx)("p",null,"Note that if you want to sample integers in the range ",(0,o.mdx)("inlineCode",{parentName:"p"},"-5")," to ",(0,o.mdx)("inlineCode",{parentName:"p"},"5"),", you need to specify the range as ",(0,o.mdx)("inlineCode",{parentName:"p"},"int(interval(-5, 5))")," (in the command line) or ",(0,o.mdx)("inlineCode",{parentName:"p"},"[-5, 5]")," (in config). If you want to sample floats in range ",(0,o.mdx)("inlineCode",{parentName:"p"},"-5")," to ",(0,o.mdx)("inlineCode",{parentName:"p"},"5"),", you need to specify the range as ",(0,o.mdx)("inlineCode",{parentName:"p"},"interval(-5, 5)")," (in the command line) or ",(0,o.mdx)("inlineCode",{parentName:"p"},"[-5.0, 5.0]")," (in config)."),(0,o.mdx)("p",null,"The Ax Sweeper assumes the optimized function is a noisy function with unknown measurement uncertainty.\nThis can be changed by overriding the ",(0,o.mdx)("inlineCode",{parentName:"p"},"is_noisy")," parameter to False, which specifies that each measurement is exact, i.e., each measurement has a measurement uncertainty of zero."),(0,o.mdx)("p",null,"If measurement uncertainty is known or can be estimated (e.g., via a heuristic or via the ",(0,o.mdx)("a",{parentName:"p",href:"https://en.wikipedia.org/wiki/Standard_error"},"standard error of the mean")," of repeated measurements), the measurement function can return the tuple ",(0,o.mdx)("inlineCode",{parentName:"p"},"(measurement_value, measurement_uncertainty)")," instead of a scalar value."),(0,o.mdx)("p",null,"The 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:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python your_app.py hydra/sweeper=ax --cfg hydra -p hydra.sweeper"',title:'"$',python:!0,"your_app.py":!0,"hydra/sweeper":"ax","--cfg":!0,hydra:!0,"-p":!0,'hydra.sweeper"':!0},"# @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")),(0,o.mdx)("p",null,"There are several standard approaches for configuring plugins. Check ",(0,o.mdx)("a",{parentName:"p",href:"/docs/patterns/configuring_plugins"},"this page")," for more information."))}h.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1e3a3c98.4e744e10.js b/assets/js/1e3a3c98.4e744e10.js deleted file mode 100644 index c987cdea75..0000000000 --- a/assets/js/1e3a3c98.4e744e10.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[5504],{15680:(e,r,n)=>{n.r(r),n.d(r,{MDXContext:()=>s,MDXProvider:()=>g,mdx:()=>y,useMDXComponents:()=>d,withMDXComponents:()=>c});var o=n(96540);function t(e,r,n){return r in e?Object.defineProperty(e,r,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[r]=n,e}function l(){return l=Object.assign||function(e){for(var r=1;r=0||(t[n]=e[n]);return t}(e,r);if(Object.getOwnPropertySymbols){var l=Object.getOwnPropertySymbols(e);for(o=0;o=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(t[n]=e[n])}return t}var s=o.createContext({}),c=function(e){return function(r){var n=d(r.components);return o.createElement(e,l({},r,{components:n}))}},d=function(e){var r=o.useContext(s),n=r;return e&&(n="function"==typeof e?e(r):i(i({},r),e)),n},g=function(e){var r=d(e.components);return o.createElement(s.Provider,{value:r},e.children)},u={inlineCode:"code",wrapper:function(e){var r=e.children;return o.createElement(o.Fragment,{},r)}},m=o.forwardRef((function(e,r){var n=e.components,t=e.mdxType,l=e.originalType,a=e.parentName,s=p(e,["components","mdxType","originalType","parentName"]),c=d(n),g=t,m=c["".concat(a,".").concat(g)]||c[g]||u[g]||l;return n?o.createElement(m,i(i({ref:r},s),{},{components:n})):o.createElement(m,i({ref:r},s))}));function y(e,r){var n=arguments,t=r&&r.mdxType;if("string"==typeof e||t){var l=n.length,a=new Array(l);a[0]=m;var i={};for(var p in r)hasOwnProperty.call(r,p)&&(i[p]=r[p]);i.originalType=e,i.mdxType="string"==typeof e?e:t,a[1]=i;for(var s=2;s{n.d(r,{A:()=>p,C:()=>s});var o=n(58168),t=n(96540),l=n(75489),a=n(44586),i=n(74098);function p(e){return t.createElement(l.default,(0,o.A)({},e,{to:(r=e.to,p=(0,i.useActiveVersion)(),(0,a.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==p?void 0:p.name)?n:"current"]+r),target:"_blank"}));var r,n,p}function s(e){var r,n=null!=(r=e.text)?r:"Example (Click Here)";return t.createElement(p,e,t.createElement("span",null,"\xa0"),t.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},17940:(e,r,n)=>{n.r(r),n.d(r,{contentTitle:()=>c,default:()=>y,frontMatter:()=>s,metadata:()=>d,toc:()=>g});var o,t=n(58168),l=n(98587),a=(n(96540),n(15680)),i=n(49595),p=["components"],s={id:"colorlog",title:"Colorlog plugin",sidebar_label:"Colorlog plugin"},c=void 0,d={unversionedId:"plugins/colorlog",id:"version-1.1/plugins/colorlog",title:"Colorlog plugin",description:"PyPI",source:"@site/versioned_docs/version-1.1/plugins/colorlog.md",sourceDirName:"plugins",slug:"/plugins/colorlog",permalink:"/docs/1.1/plugins/colorlog",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/plugins/colorlog.md",tags:[],version:"1.1",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"colorlog",title:"Colorlog plugin",sidebar_label:"Colorlog plugin"},sidebar:"version-1.1/docs",previous:{title:"Customizing Application's help",permalink:"/docs/1.1/configure_hydra/app_help"},next:{title:"Joblib Launcher plugin",permalink:"/docs/1.1/plugins/joblib_launcher"}},g=[{value:"Installation",id:"installation",children:[],level:3},{value:"Usage",id:"usage",children:[],level:3}],u=(o="GithubLink",function(e){return console.warn("Component "+o+" was not imported, exported, or provided by MDXProvider as global scope"),(0,a.mdx)("div",e)}),m={toc:g};function y(e){var r=e.components,o=(0,l.A)(e,p);return(0,a.mdx)("wrapper",(0,t.A)({},m,o,{components:r,mdxType:"MDXLayout"}),(0,a.mdx)("p",null,(0,a.mdx)("a",{parentName:"p",href:"https://pypi.org/project/hydra-colorlog/"},(0,a.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/v/hydra-colorlog",alt:"PyPI"})),"\n",(0,a.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/l/hydra-colorlog",alt:"PyPI - License"}),"\n",(0,a.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/pyversions/hydra-colorlog",alt:"PyPI - Python Version"}),"\n",(0,a.mdx)("a",{parentName:"p",href:"https://pypistats.org/packages/hydra-colorlog"},(0,a.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/dm/hydra-colorlog.svg",alt:"PyPI - Downloads"})),(0,a.mdx)(i.C,{text:"Example application",to:"plugins/hydra_colorlog/example",mdxType:"ExampleGithubLink"}),(0,a.mdx)(i.C,{text:"Plugin source",to:"plugins/hydra_colorlog",mdxType:"ExampleGithubLink"})),(0,a.mdx)("p",null,"Adds ",(0,a.mdx)("a",{class:"external",href:"https://github.com/borntyping/python-colorlog",target:"_blank"},"colorlog")," colored logs for ",(0,a.mdx)("inlineCode",{parentName:"p"},"hydra/job_logging")," and ",(0,a.mdx)("inlineCode",{parentName:"p"},"hydra/hydra_logging"),"."),(0,a.mdx)("h3",{id:"installation"},"Installation"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-commandline"},"pip install hydra_colorlog --upgrade\n")),(0,a.mdx)("h3",{id:"usage"},"Usage"),(0,a.mdx)("p",null,"Override ",(0,a.mdx)("inlineCode",{parentName:"p"},"hydra/job_logging")," and ",(0,a.mdx)("inlineCode",{parentName:"p"},"hydra/hydra_logging")," in your config:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - override hydra/job_logging: colorlog\n - override hydra/hydra_logging: colorlog\n")),(0,a.mdx)("p",null,"There are several standard approaches for configuring plugins. Check ",(0,a.mdx)("a",{parentName:"p",href:"/docs/1.1/patterns/configuring_plugins"},"this page")," for more information."),(0,a.mdx)("p",null,"See included ",(0,a.mdx)(u,{to:"plugins/hydra_colorlog/example",mdxType:"GithubLink"},"example application"),"."),(0,a.mdx)("p",null,(0,a.mdx)("img",{alt:"Colored log output",src:n(69674).A})))}y.isMDXComponent=!0},69674:(e,r,n)=>{n.d(r,{A:()=>o});const o=n.p+"assets/images/colorlog-b20147697b9d16362f62a5d0bb58347f.png"}}]); \ No newline at end of file diff --git a/assets/js/1e3a3c98.5e40ed16.js b/assets/js/1e3a3c98.5e40ed16.js new file mode 100644 index 0000000000..b984e72e8b --- /dev/null +++ b/assets/js/1e3a3c98.5e40ed16.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[5504],{15680:(e,r,n)=>{n.r(r),n.d(r,{MDXContext:()=>s,MDXProvider:()=>g,mdx:()=>y,useMDXComponents:()=>d,withMDXComponents:()=>c});var o=n(96540);function t(e,r,n){return r in e?Object.defineProperty(e,r,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[r]=n,e}function l(){return l=Object.assign||function(e){for(var r=1;r=0||(t[n]=e[n]);return t}(e,r);if(Object.getOwnPropertySymbols){var l=Object.getOwnPropertySymbols(e);for(o=0;o=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(t[n]=e[n])}return t}var s=o.createContext({}),c=function(e){return function(r){var n=d(r.components);return o.createElement(e,l({},r,{components:n}))}},d=function(e){var r=o.useContext(s),n=r;return e&&(n="function"==typeof e?e(r):i(i({},r),e)),n},g=function(e){var r=d(e.components);return o.createElement(s.Provider,{value:r},e.children)},m={inlineCode:"code",wrapper:function(e){var r=e.children;return o.createElement(o.Fragment,{},r)}},u=o.forwardRef((function(e,r){var n=e.components,t=e.mdxType,l=e.originalType,a=e.parentName,s=p(e,["components","mdxType","originalType","parentName"]),c=d(n),g=t,u=c["".concat(a,".").concat(g)]||c[g]||m[g]||l;return n?o.createElement(u,i(i({ref:r},s),{},{components:n})):o.createElement(u,i({ref:r},s))}));function y(e,r){var n=arguments,t=r&&r.mdxType;if("string"==typeof e||t){var l=n.length,a=new Array(l);a[0]=u;var i={};for(var p in r)hasOwnProperty.call(r,p)&&(i[p]=r[p]);i.originalType=e,i.mdxType="string"==typeof e?e:t,a[1]=i;for(var s=2;s{n.d(r,{A:()=>p,C:()=>s});var o=n(58168),t=n(96540),l=n(75489),a=n(44586),i=n(74098);function p(e){return t.createElement(l.default,(0,o.A)({},e,{to:(r=e.to,p=(0,i.useActiveVersion)(),(0,a.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==p?void 0:p.name)?n:"current"]+r),target:"_blank"}));var r,n,p}function s(e){var r,n=null!=(r=e.text)?r:"Example (Click Here)";return t.createElement(p,e,t.createElement("span",null,"\xa0"),t.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},17940:(e,r,n)=>{n.r(r),n.d(r,{contentTitle:()=>c,default:()=>y,frontMatter:()=>s,metadata:()=>d,toc:()=>g});var o,t=n(58168),l=n(98587),a=(n(96540),n(15680)),i=n(49595),p=["components"],s={id:"colorlog",title:"Colorlog plugin",sidebar_label:"Colorlog plugin"},c=void 0,d={unversionedId:"plugins/colorlog",id:"version-1.1/plugins/colorlog",title:"Colorlog plugin",description:"PyPI",source:"@site/versioned_docs/version-1.1/plugins/colorlog.md",sourceDirName:"plugins",slug:"/plugins/colorlog",permalink:"/docs/1.1/plugins/colorlog",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/plugins/colorlog.md",tags:[],version:"1.1",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"colorlog",title:"Colorlog plugin",sidebar_label:"Colorlog plugin"},sidebar:"version-1.1/docs",previous:{title:"Customizing Application's help",permalink:"/docs/1.1/configure_hydra/app_help"},next:{title:"Joblib Launcher plugin",permalink:"/docs/1.1/plugins/joblib_launcher"}},g=[{value:"Installation",id:"installation",children:[],level:3},{value:"Usage",id:"usage",children:[],level:3}],m=(o="GithubLink",function(e){return console.warn("Component "+o+" was not imported, exported, or provided by MDXProvider as global scope"),(0,a.mdx)("div",e)}),u={toc:g};function y(e){var r=e.components,o=(0,l.A)(e,p);return(0,a.mdx)("wrapper",(0,t.A)({},u,o,{components:r,mdxType:"MDXLayout"}),(0,a.mdx)("p",null,(0,a.mdx)("a",{parentName:"p",href:"https://pypi.org/project/hydra-colorlog/"},(0,a.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/v/hydra-colorlog",alt:"PyPI"})),"\n",(0,a.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/l/hydra-colorlog",alt:"PyPI - License"}),"\n",(0,a.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/pyversions/hydra-colorlog",alt:"PyPI - Python Version"}),"\n",(0,a.mdx)("a",{parentName:"p",href:"https://pypistats.org/packages/hydra-colorlog"},(0,a.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/dm/hydra-colorlog.svg",alt:"PyPI - Downloads"})),(0,a.mdx)(i.C,{text:"Example application",to:"plugins/hydra_colorlog/example",mdxType:"ExampleGithubLink"}),(0,a.mdx)(i.C,{text:"Plugin source",to:"plugins/hydra_colorlog",mdxType:"ExampleGithubLink"})),(0,a.mdx)("p",null,"Adds ",(0,a.mdx)("a",{class:"external",href:"https://github.com/borntyping/python-colorlog",target:"_blank"},"colorlog")," colored logs for ",(0,a.mdx)("inlineCode",{parentName:"p"},"hydra/job_logging")," and ",(0,a.mdx)("inlineCode",{parentName:"p"},"hydra/hydra_logging"),"."),(0,a.mdx)("h3",{id:"installation"},"Installation"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-commandline"},"pip install hydra_colorlog --upgrade\n")),(0,a.mdx)("h3",{id:"usage"},"Usage"),(0,a.mdx)("p",null,"Override ",(0,a.mdx)("inlineCode",{parentName:"p"},"hydra/job_logging")," and ",(0,a.mdx)("inlineCode",{parentName:"p"},"hydra/hydra_logging")," in your config:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - override hydra/job_logging: colorlog\n - override hydra/hydra_logging: colorlog\n")),(0,a.mdx)("p",null,"There are several standard approaches for configuring plugins. Check ",(0,a.mdx)("a",{parentName:"p",href:"/docs/1.1/patterns/configuring_plugins"},"this page")," for more information."),(0,a.mdx)("p",null,"See included ",(0,a.mdx)(m,{to:"plugins/hydra_colorlog/example",mdxType:"GithubLink"},"example application"),"."),(0,a.mdx)("p",null,(0,a.mdx)("img",{alt:"Colored log output",src:n(69674).A})))}y.isMDXComponent=!0},69674:(e,r,n)=>{n.d(r,{A:()=>o});const o=n.p+"assets/images/colorlog-b20147697b9d16362f62a5d0bb58347f.png"}}]); \ No newline at end of file diff --git a/assets/js/1e3f28fe.52ad50ed.js b/assets/js/1e3f28fe.52ad50ed.js new file mode 100644 index 0000000000..82797de865 --- /dev/null +++ b/assets/js/1e3f28fe.52ad50ed.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[8463],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>c,MDXProvider:()=>p,mdx:()=>y,useMDXComponents:()=>u,withMDXComponents:()=>m});var r=n(96540);function a(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(a[n]=e[n]);return a}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(a[n]=e[n])}return a}var c=r.createContext({}),m=function(e){return function(t){var n=u(t.components);return r.createElement(e,o({},t,{components:n}))}},u=function(e){var t=r.useContext(c),n=t;return e&&(n="function"==typeof e?e(t):s(s({},t),e)),n},p=function(e){var t=u(e.components);return r.createElement(c.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},f=r.forwardRef((function(e,t){var n=e.components,a=e.mdxType,o=e.originalType,i=e.parentName,c=l(e,["components","mdxType","originalType","parentName"]),m=u(n),p=a,f=m["".concat(i,".").concat(p)]||m[p]||d[p]||o;return n?r.createElement(f,s(s({ref:t},c),{},{components:n})):r.createElement(f,s({ref:t},c))}));function y(e,t){var n=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var o=n.length,i=new Array(o);i[0]=f;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s.mdxType="string"==typeof e?e:a,i[1]=s;for(var c=2;c{n.d(t,{A:()=>l,C:()=>c});var r=n(58168),a=n(96540),o=n(75489),i=n(44586),s=n(74098);function l(e){return a.createElement(o.default,(0,r.A)({},e,{to:(t=e.to,l=(0,s.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==l?void 0:l.name)?n:"current"]+t),target:"_blank"}));var t,n,l}function c(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return a.createElement(l,e,a.createElement("span",null,"\xa0"),a.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},36200:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>c,default:()=>d,frontMatter:()=>l,metadata:()=>m,toc:()=>u});var r=n(58168),a=n(98587),o=(n(96540),n(15680)),i=n(49595),s=["components"],l={id:"composition",title:"Putting it all together"},c=void 0,m={unversionedId:"tutorials/basic/your_first_app/composition",id:"version-1.2/tutorials/basic/your_first_app/composition",title:"Putting it all together",description:"As software gets more complex, we resort to modularity and composition to keep it manageable.",source:"@site/versioned_docs/version-1.2/tutorials/basic/your_first_app/6_composition.md",sourceDirName:"tutorials/basic/your_first_app",slug:"/tutorials/basic/your_first_app/composition",permalink:"/docs/1.2/tutorials/basic/your_first_app/composition",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/tutorials/basic/your_first_app/6_composition.md",tags:[],version:"1.2",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:6,frontMatter:{id:"composition",title:"Putting it all together"},sidebar:"docs",previous:{title:"Selecting default configs",permalink:"/docs/1.2/tutorials/basic/your_first_app/defaults"},next:{title:"Multi-run",permalink:"/docs/1.2/tutorials/basic/running_your_app/multi-run"}},u=[{value:"Summary",id:"summary",children:[],level:3}],p={toc:u};function d(e){var t=e.components,n=(0,a.A)(e,s);return(0,o.mdx)("wrapper",(0,r.A)({},p,n,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)(i.C,{to:"examples/tutorials/basic/your_first_hydra_app/6_composition",mdxType:"ExampleGithubLink"}),(0,o.mdx)("p",null,"As software gets more complex, we resort to modularity and composition to keep it manageable.\nWe can do the same with configs. Suppose we want our working example to support multiple databases, with\nmultiple schemas per database, and different UIs. We wouldn't write a separate class\nfor each permutation of db, schema and UI, so we shouldn't write separate configs either. We use\nthe same solution in configuration as in writing the underlying software: composition. "),(0,o.mdx)("p",null,"To do this in Hydra, we first add a ",(0,o.mdx)("inlineCode",{parentName:"p"},"schema")," and a ",(0,o.mdx)("inlineCode",{parentName:"p"},"ui")," config group:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Directory layout"',title:'"Directory','layout"':!0},"\u251c\u2500\u2500 conf\n\u2502 \u251c\u2500\u2500 config.yaml\n\u2502 \u251c\u2500\u2500 db\n\u2502 \u2502 \u251c\u2500\u2500 mysql.yaml\n\u2502 \u2502 \u2514\u2500\u2500 postgresql.yaml\n\u2502 \u251c\u2500\u2500 schema\n\u2502 \u2502 \u251c\u2500\u2500 school.yaml\n\u2502 \u2502 \u251c\u2500\u2500 support.yaml\n\u2502 \u2502 \u2514\u2500\u2500 warehouse.yaml\n\u2502 \u2514\u2500\u2500 ui\n\u2502 \u251c\u2500\u2500 full.yaml\n\u2502 \u2514\u2500\u2500 view.yaml\n\u2514\u2500\u2500 my_app.py\n")),(0,o.mdx)("p",null,"With these configs, we already have 12 possible combinations. Without composition, we would need 12 separate configs.\nA single change, such as renaming ",(0,o.mdx)("inlineCode",{parentName:"p"},"db.user")," to ",(0,o.mdx)("inlineCode",{parentName:"p"},"db.username"),", requires editing all 12 of them.\nThis is a maintenance nightmare."),(0,o.mdx)("p",null,"Composition can come to the rescue.\nInstead of creating 12 different config files, that fully specify each\nconfig, create a single config that specifies the different configuration dimensions, and the default for each."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - db: mysql\n - ui: full\n - schema: school\n")),(0,o.mdx)("p",null,"The resulting configuration is a composition of the ",(0,o.mdx)("em",{parentName:"p"},"mysql")," database, the ",(0,o.mdx)("em",{parentName:"p"},"full")," ui, and the ",(0,o.mdx)("em",{parentName:"p"},"school")," schema\n(which we are seeing for the first time here):"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py\ndb:\n driver: mysql\n user: omry\n pass: secret\nui:\n windows:\n create_db: true\n view: true\nschema:\n database: school\n tables:\n - name: students\n fields:\n - name: string\n - class: int\n - name: exams\n fields:\n - profession: string\n - time: data\n - class: int\n")),(0,o.mdx)("p",null,"Stay tuned to see how to run all of the combinations automatically (",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.2/tutorials/basic/running_your_app/multi-run"},"Multi-run"),")."),(0,o.mdx)("h3",{id:"summary"},"Summary"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"The addition of each new db, schema, or ui only requires a single file."),(0,o.mdx)("li",{parentName:"ul"},"Each config group can have a default specified in the Defaults List."),(0,o.mdx)("li",{parentName:"ul"},"Any combination can be composed by selecting the desired option from each config group in the\nDefaults List or the command line.")))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1e3f28fe.fdca7247.js b/assets/js/1e3f28fe.fdca7247.js deleted file mode 100644 index ed7d297096..0000000000 --- a/assets/js/1e3f28fe.fdca7247.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[8463],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>c,MDXProvider:()=>p,mdx:()=>y,useMDXComponents:()=>u,withMDXComponents:()=>m});var r=n(96540);function a(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(a[n]=e[n]);return a}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(a[n]=e[n])}return a}var c=r.createContext({}),m=function(e){return function(t){var n=u(t.components);return r.createElement(e,o({},t,{components:n}))}},u=function(e){var t=r.useContext(c),n=t;return e&&(n="function"==typeof e?e(t):s(s({},t),e)),n},p=function(e){var t=u(e.components);return r.createElement(c.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},f=r.forwardRef((function(e,t){var n=e.components,a=e.mdxType,o=e.originalType,i=e.parentName,c=l(e,["components","mdxType","originalType","parentName"]),m=u(n),p=a,f=m["".concat(i,".").concat(p)]||m[p]||d[p]||o;return n?r.createElement(f,s(s({ref:t},c),{},{components:n})):r.createElement(f,s({ref:t},c))}));function y(e,t){var n=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var o=n.length,i=new Array(o);i[0]=f;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s.mdxType="string"==typeof e?e:a,i[1]=s;for(var c=2;c{n.d(t,{A:()=>l,C:()=>c});var r=n(58168),a=n(96540),o=n(75489),i=n(44586),s=n(74098);function l(e){return a.createElement(o.default,(0,r.A)({},e,{to:(t=e.to,l=(0,s.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==l?void 0:l.name)?n:"current"]+t),target:"_blank"}));var t,n,l}function c(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return a.createElement(l,e,a.createElement("span",null,"\xa0"),a.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},36200:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>c,default:()=>d,frontMatter:()=>l,metadata:()=>m,toc:()=>u});var r=n(58168),a=n(98587),o=(n(96540),n(15680)),i=n(49595),s=["components"],l={id:"composition",title:"Putting it all together"},c=void 0,m={unversionedId:"tutorials/basic/your_first_app/composition",id:"version-1.2/tutorials/basic/your_first_app/composition",title:"Putting it all together",description:"As software gets more complex, we resort to modularity and composition to keep it manageable.",source:"@site/versioned_docs/version-1.2/tutorials/basic/your_first_app/6_composition.md",sourceDirName:"tutorials/basic/your_first_app",slug:"/tutorials/basic/your_first_app/composition",permalink:"/docs/1.2/tutorials/basic/your_first_app/composition",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/tutorials/basic/your_first_app/6_composition.md",tags:[],version:"1.2",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:6,frontMatter:{id:"composition",title:"Putting it all together"},sidebar:"docs",previous:{title:"Selecting default configs",permalink:"/docs/1.2/tutorials/basic/your_first_app/defaults"},next:{title:"Multi-run",permalink:"/docs/1.2/tutorials/basic/running_your_app/multi-run"}},u=[{value:"Summary",id:"summary",children:[],level:3}],p={toc:u};function d(e){var t=e.components,n=(0,a.A)(e,s);return(0,o.mdx)("wrapper",(0,r.A)({},p,n,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)(i.C,{to:"examples/tutorials/basic/your_first_hydra_app/6_composition",mdxType:"ExampleGithubLink"}),(0,o.mdx)("p",null,"As software gets more complex, we resort to modularity and composition to keep it manageable.\nWe can do the same with configs. Suppose we want our working example to support multiple databases, with\nmultiple schemas per database, and different UIs. We wouldn't write a separate class\nfor each permutation of db, schema and UI, so we shouldn't write separate configs either. We use\nthe same solution in configuration as in writing the underlying software: composition. "),(0,o.mdx)("p",null,"To do this in Hydra, we first add a ",(0,o.mdx)("inlineCode",{parentName:"p"},"schema")," and a ",(0,o.mdx)("inlineCode",{parentName:"p"},"ui")," config group:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Directory layout"',title:'"Directory','layout"':!0},"\u251c\u2500\u2500 conf\n\u2502 \u251c\u2500\u2500 config.yaml\n\u2502 \u251c\u2500\u2500 db\n\u2502 \u2502 \u251c\u2500\u2500 mysql.yaml\n\u2502 \u2502 \u2514\u2500\u2500 postgresql.yaml\n\u2502 \u251c\u2500\u2500 schema\n\u2502 \u2502 \u251c\u2500\u2500 school.yaml\n\u2502 \u2502 \u251c\u2500\u2500 support.yaml\n\u2502 \u2502 \u2514\u2500\u2500 warehouse.yaml\n\u2502 \u2514\u2500\u2500 ui\n\u2502 \u251c\u2500\u2500 full.yaml\n\u2502 \u2514\u2500\u2500 view.yaml\n\u2514\u2500\u2500 my_app.py\n")),(0,o.mdx)("p",null,"With these configs, we already have 12 possible combinations. Without composition, we would need 12 separate configs.\nA single change, such as renaming ",(0,o.mdx)("inlineCode",{parentName:"p"},"db.user")," to ",(0,o.mdx)("inlineCode",{parentName:"p"},"db.username"),", requires editing all 12 of them.\nThis is a maintenance nightmare."),(0,o.mdx)("p",null,"Composition can come to the rescue.\nInstead of creating 12 different config files, that fully specify each\nconfig, create a single config that specifies the different configuration dimensions, and the default for each."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - db: mysql\n - ui: full\n - schema: school\n")),(0,o.mdx)("p",null,"The resulting configuration is a composition of the ",(0,o.mdx)("em",{parentName:"p"},"mysql")," database, the ",(0,o.mdx)("em",{parentName:"p"},"full")," ui, and the ",(0,o.mdx)("em",{parentName:"p"},"school")," schema\n(which we are seeing for the first time here):"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py\ndb:\n driver: mysql\n user: omry\n pass: secret\nui:\n windows:\n create_db: true\n view: true\nschema:\n database: school\n tables:\n - name: students\n fields:\n - name: string\n - class: int\n - name: exams\n fields:\n - profession: string\n - time: data\n - class: int\n")),(0,o.mdx)("p",null,"Stay tuned to see how to run all of the combinations automatically (",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.2/tutorials/basic/running_your_app/multi-run"},"Multi-run"),")."),(0,o.mdx)("h3",{id:"summary"},"Summary"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"The addition of each new db, schema, or ui only requires a single file."),(0,o.mdx)("li",{parentName:"ul"},"Each config group can have a default specified in the Defaults List."),(0,o.mdx)("li",{parentName:"ul"},"Any combination can be composed by selecting the desired option from each config group in the\nDefaults List or the command line.")))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1f1bf95b.5425d6e1.js b/assets/js/1f1bf95b.5425d6e1.js new file mode 100644 index 0000000000..2708fb09e1 --- /dev/null +++ b/assets/js/1f1bf95b.5425d6e1.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[1629],{15680:(e,t,r)=>{r.r(t),r.d(t,{MDXContext:()=>c,MDXProvider:()=>l,mdx:()=>b,useMDXComponents:()=>u,withMDXComponents:()=>d});var n=r(96540);function o(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(o[r]=e[r]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(o[r]=e[r])}return o}var c=n.createContext({}),d=function(e){return function(t){var r=u(t.components);return n.createElement(e,a({},t,{components:r}))}},u=function(e){var t=n.useContext(c),r=t;return e&&(r="function"==typeof e?e(t):p(p({},t),e)),r},l=function(e){var t=u(e.components);return n.createElement(c.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},y=n.forwardRef((function(e,t){var r=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,c=s(e,["components","mdxType","originalType","parentName"]),d=u(r),l=o,y=d["".concat(i,".").concat(l)]||d[l]||m[l]||a;return r?n.createElement(y,p(p({ref:t},c),{},{components:r})):n.createElement(y,p({ref:t},c))}));function b(e,t){var r=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=r.length,i=new Array(a);i[0]=y;var p={};for(var s in t)hasOwnProperty.call(t,s)&&(p[s]=t[s]);p.originalType=e,p.mdxType="string"==typeof e?e:o,i[1]=p;for(var c=2;c{r.r(t),r.d(t,{contentTitle:()=>s,default:()=>l,frontMatter:()=>p,metadata:()=>c,toc:()=>d});var n=r(58168),o=r(98587),a=(r(96540),r(15680)),i=["components"],p={id:"jupyter_notebooks",title:"Hydra in Jupyter Notebooks"},s=void 0,c={unversionedId:"advanced/jupyter_notebooks",id:"version-1.1/advanced/jupyter_notebooks",title:"Hydra in Jupyter Notebooks",description:"Hydra supports config composition inside Jupyter notebooks via the Compose API.",source:"@site/versioned_docs/version-1.1/advanced/jupyter_notebooks.md",sourceDirName:"advanced",slug:"/advanced/jupyter_notebooks",permalink:"/docs/1.1/advanced/jupyter_notebooks",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/advanced/jupyter_notebooks.md",tags:[],version:"1.1",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"jupyter_notebooks",title:"Hydra in Jupyter Notebooks"},sidebar:"version-1.1/docs",previous:{title:"Application packaging",permalink:"/docs/1.1/advanced/app_packaging"},next:{title:"Hydra in Unit Tests",permalink:"/docs/1.1/advanced/unit_testing"}},d=[],u={toc:d};function l(e){var t=e.components,r=(0,o.A)(e,i);return(0,a.mdx)("wrapper",(0,n.A)({},u,r,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)("p",null,"Hydra supports config composition inside Jupyter notebooks via the ",(0,a.mdx)("a",{parentName:"p",href:"/docs/1.1/advanced/compose_api"},"Compose API"),". "),(0,a.mdx)("p",null,"Run the Notebook in a the Binder to see a live demo, or open the Notebook source on GitHub."),(0,a.mdx)("p",null,(0,a.mdx)("a",{parentName:"p",href:"https://mybinder.org/v2/gh/facebookresearch/hydra/main?filepath=examples%252jupyter_notebooks"},(0,a.mdx)("img",{parentName:"a",src:"https://mybinder.org/badge_logo.svg",alt:"Binder"})),"\n",(0,a.mdx)("a",{parentName:"p",href:"https://github.com/facebookresearch/hydra//tree/main/examples/jupyter_notebooks/"},(0,a.mdx)("img",{parentName:"a",src:"https://img.shields.io/badge/-Notebooks%20source-informational",alt:"Notebook source"}))))}l.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1f1bf95b.80dd92c7.js b/assets/js/1f1bf95b.80dd92c7.js deleted file mode 100644 index ad25b1424d..0000000000 --- a/assets/js/1f1bf95b.80dd92c7.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[1629],{15680:(e,t,r)=>{r.r(t),r.d(t,{MDXContext:()=>c,MDXProvider:()=>l,mdx:()=>f,useMDXComponents:()=>u,withMDXComponents:()=>d});var n=r(96540);function o(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(o[r]=e[r]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(o[r]=e[r])}return o}var c=n.createContext({}),d=function(e){return function(t){var r=u(t.components);return n.createElement(e,a({},t,{components:r}))}},u=function(e){var t=n.useContext(c),r=t;return e&&(r="function"==typeof e?e(t):p(p({},t),e)),r},l=function(e){var t=u(e.components);return n.createElement(c.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},y=n.forwardRef((function(e,t){var r=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,c=s(e,["components","mdxType","originalType","parentName"]),d=u(r),l=o,y=d["".concat(i,".").concat(l)]||d[l]||m[l]||a;return r?n.createElement(y,p(p({ref:t},c),{},{components:r})):n.createElement(y,p({ref:t},c))}));function f(e,t){var r=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=r.length,i=new Array(a);i[0]=y;var p={};for(var s in t)hasOwnProperty.call(t,s)&&(p[s]=t[s]);p.originalType=e,p.mdxType="string"==typeof e?e:o,i[1]=p;for(var c=2;c{r.r(t),r.d(t,{contentTitle:()=>s,default:()=>l,frontMatter:()=>p,metadata:()=>c,toc:()=>d});var n=r(58168),o=r(98587),a=(r(96540),r(15680)),i=["components"],p={id:"jupyter_notebooks",title:"Hydra in Jupyter Notebooks"},s=void 0,c={unversionedId:"advanced/jupyter_notebooks",id:"version-1.1/advanced/jupyter_notebooks",title:"Hydra in Jupyter Notebooks",description:"Hydra supports config composition inside Jupyter notebooks via the Compose API.",source:"@site/versioned_docs/version-1.1/advanced/jupyter_notebooks.md",sourceDirName:"advanced",slug:"/advanced/jupyter_notebooks",permalink:"/docs/1.1/advanced/jupyter_notebooks",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/advanced/jupyter_notebooks.md",tags:[],version:"1.1",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"jupyter_notebooks",title:"Hydra in Jupyter Notebooks"},sidebar:"version-1.1/docs",previous:{title:"Application packaging",permalink:"/docs/1.1/advanced/app_packaging"},next:{title:"Hydra in Unit Tests",permalink:"/docs/1.1/advanced/unit_testing"}},d=[],u={toc:d};function l(e){var t=e.components,r=(0,o.A)(e,i);return(0,a.mdx)("wrapper",(0,n.A)({},u,r,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)("p",null,"Hydra supports config composition inside Jupyter notebooks via the ",(0,a.mdx)("a",{parentName:"p",href:"/docs/1.1/advanced/compose_api"},"Compose API"),". "),(0,a.mdx)("p",null,"Run the Notebook in a the Binder to see a live demo, or open the Notebook source on GitHub."),(0,a.mdx)("p",null,(0,a.mdx)("a",{parentName:"p",href:"https://mybinder.org/v2/gh/facebookresearch/hydra/main?filepath=examples%252jupyter_notebooks"},(0,a.mdx)("img",{parentName:"a",src:"https://mybinder.org/badge_logo.svg",alt:"Binder"})),"\n",(0,a.mdx)("a",{parentName:"p",href:"https://github.com/facebookresearch/hydra//tree/main/examples/jupyter_notebooks/"},(0,a.mdx)("img",{parentName:"a",src:"https://img.shields.io/badge/-Notebooks%20source-informational",alt:"Notebook source"}))))}l.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1f4529b5.4fdc357f.js b/assets/js/1f4529b5.4fdc357f.js deleted file mode 100644 index 442805a009..0000000000 --- a/assets/js/1f4529b5.4fdc357f.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[8075],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>c,MDXProvider:()=>s,mdx:()=>f,useMDXComponents:()=>m,withMDXComponents:()=>p});var a=t(96540);function r(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(r[t]=e[t]);return r}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(r[t]=e[t])}return r}var c=a.createContext({}),p=function(e){return function(n){var t=m(n.components);return a.createElement(e,i({},n,{components:t}))}},m=function(e){var n=a.useContext(c),t=n;return e&&(t="function"==typeof e?e(n):d(d({},n),e)),t},s=function(e){var n=m(e.components);return a.createElement(c.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},g=a.forwardRef((function(e,n){var t=e.components,r=e.mdxType,i=e.originalType,o=e.parentName,c=l(e,["components","mdxType","originalType","parentName"]),p=m(t),s=r,g=p["".concat(o,".").concat(s)]||p[s]||u[s]||i;return t?a.createElement(g,d(d({ref:n},c),{},{components:t})):a.createElement(g,d({ref:n},c))}));function f(e,n){var t=arguments,r=n&&n.mdxType;if("string"==typeof e||r){var i=t.length,o=new Array(i);o[0]=g;var d={};for(var l in n)hasOwnProperty.call(n,l)&&(d[l]=n[l]);d.originalType=e,d.mdxType="string"==typeof e?e:r,o[1]=d;for(var c=2;c{t.r(n),t.d(n,{contentTitle:()=>l,default:()=>s,frontMatter:()=>d,metadata:()=>c,toc:()=>p});var a=t(58168),r=t(98587),i=(t(96540),t(15680)),o=["components"],d={id:"adding_a_package_directive",title:"Adding an @package directive",hide_title:!0},l=void 0,c={unversionedId:"upgrades/0.11_to_1.0/adding_a_package_directive",id:"version-1.1/upgrades/0.11_to_1.0/adding_a_package_directive",title:"Adding an @package directive",description:"Adding an @package directive",source:"@site/versioned_docs/version-1.1/upgrades/0.11_to_1.0/adding_a_package_directive.md",sourceDirName:"upgrades/0.11_to_1.0",slug:"/upgrades/0.11_to_1.0/adding_a_package_directive",permalink:"/docs/1.1/upgrades/0.11_to_1.0/adding_a_package_directive",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/upgrades/0.11_to_1.0/adding_a_package_directive.md",tags:[],version:"1.1",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"adding_a_package_directive",title:"Adding an @package directive",hide_title:!0},sidebar:"version-1.1/docs",previous:{title:"Config path changes",permalink:"/docs/1.1/upgrades/0.11_to_1.0/config_path_changes"},next:{title:"strict flag mode deprecation",permalink:"/docs/1.1/upgrades/0.11_to_1.0/strict_mode_flag_deprecated"}},p=[{value:"Adding an @package directive",id:"adding-an-package-directive",children:[],level:2},{value:"Upgrade instructions:",id:"upgrade-instructions",children:[{value:"Recommended (~10 seconds per config file):",id:"recommended-10-seconds-per-config-file",children:[],level:3},{value:"Alternative (not recommended):",id:"alternative-not-recommended",children:[],level:3},{value:"Example for case 1:",id:"example-for-case-1",children:[{value:"Before",id:"before",children:[],level:4},{value:"After",id:"after",children:[],level:4}],level:3},{value:"Example for case 2:",id:"example-for-case-2",children:[],level:3}],level:2}],m={toc:p};function s(e){var n=e.components,t=(0,r.A)(e,o);return(0,i.mdx)("wrapper",(0,a.A)({},m,t,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)("h2",{id:"adding-an-package-directive"},"Adding an @package directive"),(0,i.mdx)("p",null,"Hydra 1.0 introduces the concept of a config ",(0,i.mdx)("inlineCode",{parentName:"p"},"package"),". A ",(0,i.mdx)("inlineCode",{parentName:"p"},"package")," is the common parent\npath of all nodes in the config file."),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"In Hydra 0.11, there was an implicit default of ",(0,i.mdx)("inlineCode",{parentName:"li"},"_global_"),' ("")'),(0,i.mdx)("li",{parentName:"ul"},"In Hydra 1.1 the default will be ",(0,i.mdx)("inlineCode",{parentName:"li"},"_group_")," (the name of the config group)."),(0,i.mdx)("li",{parentName:"ul"},"Hydra 1.0 maintains the implicit default of ",(0,i.mdx)("inlineCode",{parentName:"li"},"_global_")," and issues a warning for\nany config group file without a ",(0,i.mdx)("inlineCode",{parentName:"li"},"@package")," directive.")),(0,i.mdx)("p",null,"By adding an explicit ",(0,i.mdx)("inlineCode",{parentName:"p"},"@package")," to these configs now, you guarantee that your configs\nwill not break when you upgrade to Hydra 1.1."),(0,i.mdx)("p",null,"The ",(0,i.mdx)("inlineCode",{parentName:"p"},"@package")," directive is described in details ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.1/advanced/overriding_packages"},"here"),". "),(0,i.mdx)("h2",{id:"upgrade-instructions"},"Upgrade instructions:"),(0,i.mdx)("h3",{id:"recommended-10-seconds-per-config-file"},"Recommended (~10 seconds per config file):"),(0,i.mdx)("p",null,(0,i.mdx)("inlineCode",{parentName:"p"},"Case 1"),": For config files where the common parent path matches the config group name: "),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"Add ",(0,i.mdx)("inlineCode",{parentName:"li"},"# @package _group_")," to the top of every config group file"),(0,i.mdx)("li",{parentName:"ul"},"Remove the common parent path config file like in the example below.")),(0,i.mdx)("p",null,(0,i.mdx)("inlineCode",{parentName:"p"},"Case 2"),": For files without a common parent path:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"Add ",(0,i.mdx)("inlineCode",{parentName:"li"},"# @package _global_"),".")),(0,i.mdx)("h3",{id:"alternative-not-recommended"},"Alternative (not recommended):"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"If you do not want to restructure the config at this time use ",(0,i.mdx)("inlineCode",{parentName:"li"},"Case 2")," for all your config files.")),(0,i.mdx)("h3",{id:"example-for-case-1"},"Example for ",(0,i.mdx)("inlineCode",{parentName:"h3"},"case 1"),":"),(0,i.mdx)("h4",{id:"before"},"Before"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml"',title:'"db/mysql.yaml"'},"db:\n driver: mysql\n host: localhost\n port: 3306\n")),(0,i.mdx)("h4",{id:"after"},"After"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml"',title:'"db/mysql.yaml"'},"# @package _group_\ndriver: mysql\nhost: localhost\nport: 3306\n")),(0,i.mdx)("p",null,"The interpretations of the before and after files are identical."),(0,i.mdx)("h3",{id:"example-for-case-2"},"Example for ",(0,i.mdx)("inlineCode",{parentName:"h3"},"case 2"),":"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="env/prod.yaml"',title:'"env/prod.yaml"'},"# @package _global_\ndb:\n driver: mysql\n host: 10.0.0.11\n port: 3306\n\nwebserver:\n host: 10.0.0.11\n port: 443\n")))}s.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1f4529b5.e25769a2.js b/assets/js/1f4529b5.e25769a2.js new file mode 100644 index 0000000000..fbd2b84c78 --- /dev/null +++ b/assets/js/1f4529b5.e25769a2.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[8075],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>c,MDXProvider:()=>s,mdx:()=>f,useMDXComponents:()=>m,withMDXComponents:()=>p});var a=t(96540);function r(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(r[t]=e[t]);return r}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(r[t]=e[t])}return r}var c=a.createContext({}),p=function(e){return function(n){var t=m(n.components);return a.createElement(e,i({},n,{components:t}))}},m=function(e){var n=a.useContext(c),t=n;return e&&(t="function"==typeof e?e(n):d(d({},n),e)),t},s=function(e){var n=m(e.components);return a.createElement(c.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},g=a.forwardRef((function(e,n){var t=e.components,r=e.mdxType,i=e.originalType,o=e.parentName,c=l(e,["components","mdxType","originalType","parentName"]),p=m(t),s=r,g=p["".concat(o,".").concat(s)]||p[s]||u[s]||i;return t?a.createElement(g,d(d({ref:n},c),{},{components:t})):a.createElement(g,d({ref:n},c))}));function f(e,n){var t=arguments,r=n&&n.mdxType;if("string"==typeof e||r){var i=t.length,o=new Array(i);o[0]=g;var d={};for(var l in n)hasOwnProperty.call(n,l)&&(d[l]=n[l]);d.originalType=e,d.mdxType="string"==typeof e?e:r,o[1]=d;for(var c=2;c{t.r(n),t.d(n,{contentTitle:()=>l,default:()=>s,frontMatter:()=>d,metadata:()=>c,toc:()=>p});var a=t(58168),r=t(98587),i=(t(96540),t(15680)),o=["components"],d={id:"adding_a_package_directive",title:"Adding an @package directive",hide_title:!0},l=void 0,c={unversionedId:"upgrades/0.11_to_1.0/adding_a_package_directive",id:"version-1.1/upgrades/0.11_to_1.0/adding_a_package_directive",title:"Adding an @package directive",description:"Adding an @package directive",source:"@site/versioned_docs/version-1.1/upgrades/0.11_to_1.0/adding_a_package_directive.md",sourceDirName:"upgrades/0.11_to_1.0",slug:"/upgrades/0.11_to_1.0/adding_a_package_directive",permalink:"/docs/1.1/upgrades/0.11_to_1.0/adding_a_package_directive",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/upgrades/0.11_to_1.0/adding_a_package_directive.md",tags:[],version:"1.1",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"adding_a_package_directive",title:"Adding an @package directive",hide_title:!0},sidebar:"version-1.1/docs",previous:{title:"Config path changes",permalink:"/docs/1.1/upgrades/0.11_to_1.0/config_path_changes"},next:{title:"strict flag mode deprecation",permalink:"/docs/1.1/upgrades/0.11_to_1.0/strict_mode_flag_deprecated"}},p=[{value:"Adding an @package directive",id:"adding-an-package-directive",children:[],level:2},{value:"Upgrade instructions:",id:"upgrade-instructions",children:[{value:"Recommended (~10 seconds per config file):",id:"recommended-10-seconds-per-config-file",children:[],level:3},{value:"Alternative (not recommended):",id:"alternative-not-recommended",children:[],level:3},{value:"Example for case 1:",id:"example-for-case-1",children:[{value:"Before",id:"before",children:[],level:4},{value:"After",id:"after",children:[],level:4}],level:3},{value:"Example for case 2:",id:"example-for-case-2",children:[],level:3}],level:2}],m={toc:p};function s(e){var n=e.components,t=(0,r.A)(e,o);return(0,i.mdx)("wrapper",(0,a.A)({},m,t,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)("h2",{id:"adding-an-package-directive"},"Adding an @package directive"),(0,i.mdx)("p",null,"Hydra 1.0 introduces the concept of a config ",(0,i.mdx)("inlineCode",{parentName:"p"},"package"),". A ",(0,i.mdx)("inlineCode",{parentName:"p"},"package")," is the common parent\npath of all nodes in the config file."),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"In Hydra 0.11, there was an implicit default of ",(0,i.mdx)("inlineCode",{parentName:"li"},"_global_"),' ("")'),(0,i.mdx)("li",{parentName:"ul"},"In Hydra 1.1 the default will be ",(0,i.mdx)("inlineCode",{parentName:"li"},"_group_")," (the name of the config group)."),(0,i.mdx)("li",{parentName:"ul"},"Hydra 1.0 maintains the implicit default of ",(0,i.mdx)("inlineCode",{parentName:"li"},"_global_")," and issues a warning for\nany config group file without a ",(0,i.mdx)("inlineCode",{parentName:"li"},"@package")," directive.")),(0,i.mdx)("p",null,"By adding an explicit ",(0,i.mdx)("inlineCode",{parentName:"p"},"@package")," to these configs now, you guarantee that your configs\nwill not break when you upgrade to Hydra 1.1."),(0,i.mdx)("p",null,"The ",(0,i.mdx)("inlineCode",{parentName:"p"},"@package")," directive is described in details ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.1/advanced/overriding_packages"},"here"),". "),(0,i.mdx)("h2",{id:"upgrade-instructions"},"Upgrade instructions:"),(0,i.mdx)("h3",{id:"recommended-10-seconds-per-config-file"},"Recommended (~10 seconds per config file):"),(0,i.mdx)("p",null,(0,i.mdx)("inlineCode",{parentName:"p"},"Case 1"),": For config files where the common parent path matches the config group name: "),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"Add ",(0,i.mdx)("inlineCode",{parentName:"li"},"# @package _group_")," to the top of every config group file"),(0,i.mdx)("li",{parentName:"ul"},"Remove the common parent path config file like in the example below.")),(0,i.mdx)("p",null,(0,i.mdx)("inlineCode",{parentName:"p"},"Case 2"),": For files without a common parent path:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"Add ",(0,i.mdx)("inlineCode",{parentName:"li"},"# @package _global_"),".")),(0,i.mdx)("h3",{id:"alternative-not-recommended"},"Alternative (not recommended):"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"If you do not want to restructure the config at this time use ",(0,i.mdx)("inlineCode",{parentName:"li"},"Case 2")," for all your config files.")),(0,i.mdx)("h3",{id:"example-for-case-1"},"Example for ",(0,i.mdx)("inlineCode",{parentName:"h3"},"case 1"),":"),(0,i.mdx)("h4",{id:"before"},"Before"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml"',title:'"db/mysql.yaml"'},"db:\n driver: mysql\n host: localhost\n port: 3306\n")),(0,i.mdx)("h4",{id:"after"},"After"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml"',title:'"db/mysql.yaml"'},"# @package _group_\ndriver: mysql\nhost: localhost\nport: 3306\n")),(0,i.mdx)("p",null,"The interpretations of the before and after files are identical."),(0,i.mdx)("h3",{id:"example-for-case-2"},"Example for ",(0,i.mdx)("inlineCode",{parentName:"h3"},"case 2"),":"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="env/prod.yaml"',title:'"env/prod.yaml"'},"# @package _global_\ndb:\n driver: mysql\n host: 10.0.0.11\n port: 3306\n\nwebserver:\n host: 10.0.0.11\n port: 443\n")))}s.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/208d083d.938ab128.js b/assets/js/208d083d.938ab128.js new file mode 100644 index 0000000000..9760378cda --- /dev/null +++ b/assets/js/208d083d.938ab128.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3828],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>p,MDXProvider:()=>d,mdx:()=>f,useMDXComponents:()=>c,withMDXComponents:()=>u});var r=n(96540);function a(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(a[n]=e[n]);return a}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(a[n]=e[n])}return a}var p=r.createContext({}),u=function(e){return function(t){var n=c(t.components);return r.createElement(e,o({},t,{components:n}))}},c=function(e){var t=r.useContext(p),n=t;return e&&(n="function"==typeof e?e(t):s(s({},t),e)),n},d=function(e){var t=c(e.components);return r.createElement(p.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},h=r.forwardRef((function(e,t){var n=e.components,a=e.mdxType,o=e.originalType,i=e.parentName,p=l(e,["components","mdxType","originalType","parentName"]),u=c(n),d=a,h=u["".concat(i,".").concat(d)]||u[d]||m[d]||o;return n?r.createElement(h,s(s({ref:t},p),{},{components:n})):r.createElement(h,s({ref:t},p))}));function f(e,t){var n=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var o=n.length,i=new Array(o);i[0]=h;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s.mdxType="string"==typeof e?e:a,i[1]=s;for(var p=2;p{n.r(t),n.d(t,{contentTitle:()=>l,default:()=>d,frontMatter:()=>s,metadata:()=>p,toc:()=>u});var r=n(58168),a=n(98587),o=(n(96540),n(15680)),i=["components"],s={id:"multi-run",title:"Multi-run",sidebar_label:"Multi-run"},l=void 0,p={unversionedId:"tutorials/basic/running_your_app/multi-run",id:"version-1.1/tutorials/basic/running_your_app/multi-run",title:"Multi-run",description:"Sometimes you want to run the same application with multiple different configurations.",source:"@site/versioned_docs/version-1.1/tutorials/basic/running_your_app/2_multirun.md",sourceDirName:"tutorials/basic/running_your_app",slug:"/tutorials/basic/running_your_app/multi-run",permalink:"/docs/1.1/tutorials/basic/running_your_app/multi-run",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/tutorials/basic/running_your_app/2_multirun.md",tags:[],version:"1.1",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:2,frontMatter:{id:"multi-run",title:"Multi-run",sidebar_label:"Multi-run"},sidebar:"version-1.1/docs",previous:{title:"Putting it all together",permalink:"/docs/1.1/tutorials/basic/your_first_app/composition"},next:{title:"Output/Working directory",permalink:"/docs/1.1/tutorials/basic/running_your_app/working_directory"}},u=[{value:"Additional sweep types",id:"additional-sweep-types",children:[],level:3},{value:"Sweeper",id:"sweeper",children:[],level:3},{value:"Launcher",id:"launcher",children:[],level:3}],c={toc:u};function d(e){var t=e.components,n=(0,a.A)(e,i);return(0,o.mdx)("wrapper",(0,r.A)({},c,n,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"Sometimes you want to run the same application with multiple different configurations.",(0,o.mdx)("br",{parentName:"p"}),"\n","E.g. running a performance test on each of the databases with each of the schemas."),(0,o.mdx)("p",null,"Use the ",(0,o.mdx)("inlineCode",{parentName:"p"},"--multirun")," (",(0,o.mdx)("inlineCode",{parentName:"p"},"-m"),") flag and pass a comma separated list specifying the values for each dimension you want to sweep."),(0,o.mdx)("p",null,"The following sweeps over all combinations of the dbs and schemas."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="$ python my_app.py -m db=mysql,postgresql schema=warehouse,support,school"',title:'"$',python:!0,"my_app.py":!0,"-m":!0,db:"mysql,postgresql",schema:'warehouse,support,school"'},"[2021-01-20 17:25:03,317][HYDRA] Launching 6 jobs locally\n[2021-01-20 17:25:03,318][HYDRA] #0 : db=mysql schema=warehouse\n[2021-01-20 17:25:03,458][HYDRA] #1 : db=mysql schema=support\n[2021-01-20 17:25:03,602][HYDRA] #2 : db=mysql schema=school\n[2021-01-20 17:25:03,755][HYDRA] #3 : db=postgresql schema=warehouse\n[2021-01-20 17:25:03,895][HYDRA] #4 : db=postgresql schema=support\n[2021-01-20 17:25:04,040][HYDRA] #5 : db=postgresql schema=school\n")),(0,o.mdx)("p",null,"The printed configurations have been omitted for brevity."),(0,o.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,o.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,o.mdx)("h5",{parentName:"div"},(0,o.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,o.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,o.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,o.mdx)("div",{parentName:"div",className:"admonition-content"},(0,o.mdx)("p",{parentName:"div"},"Hydra composes configs lazily at job launching time. If you change code or configs after launching a job/sweep, the final\ncomposed configs might be impacted."))),(0,o.mdx)("h3",{id:"additional-sweep-types"},"Additional sweep types"),(0,o.mdx)("p",null,"Hydra supports other kinds of sweeps, e.g:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},"x=range(1,10) # 1-9\nschema=glob(*) # warehouse,support,school\nschema=glob(*,exclude=w*) # support,school\n")),(0,o.mdx)("p",null,"See the ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.1/advanced/override_grammar/extended"},"Extended Override syntax")," for details."),(0,o.mdx)("h3",{id:"sweeper"},"Sweeper"),(0,o.mdx)("p",null,"The default sweeping logic is built into Hydra. Additional sweepers are available as plugins.\nFor example, the ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.1/plugins/ax_sweeper"},"Ax Sweeper")," can automatically find the best parameter combination!"),(0,o.mdx)("h3",{id:"launcher"},"Launcher"),(0,o.mdx)("p",null,"By default, Hydra runs your multi-run jobs locally and serially.\nOther launchers are available as plugins for launching in parallel and on different clusters. For example, the ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.1/plugins/joblib_launcher"},"JobLib Launcher"),"\ncan execute the different parameter combinations in parallel on your local machine using multi-processing."))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/208d083d.d815ef70.js b/assets/js/208d083d.d815ef70.js deleted file mode 100644 index e12884e18e..0000000000 --- a/assets/js/208d083d.d815ef70.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3828],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>p,MDXProvider:()=>d,mdx:()=>f,useMDXComponents:()=>c,withMDXComponents:()=>u});var r=n(96540);function a(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(a[n]=e[n]);return a}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(a[n]=e[n])}return a}var p=r.createContext({}),u=function(e){return function(t){var n=c(t.components);return r.createElement(e,o({},t,{components:n}))}},c=function(e){var t=r.useContext(p),n=t;return e&&(n="function"==typeof e?e(t):s(s({},t),e)),n},d=function(e){var t=c(e.components);return r.createElement(p.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},h=r.forwardRef((function(e,t){var n=e.components,a=e.mdxType,o=e.originalType,i=e.parentName,p=l(e,["components","mdxType","originalType","parentName"]),u=c(n),d=a,h=u["".concat(i,".").concat(d)]||u[d]||m[d]||o;return n?r.createElement(h,s(s({ref:t},p),{},{components:n})):r.createElement(h,s({ref:t},p))}));function f(e,t){var n=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var o=n.length,i=new Array(o);i[0]=h;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s.mdxType="string"==typeof e?e:a,i[1]=s;for(var p=2;p{n.r(t),n.d(t,{contentTitle:()=>l,default:()=>d,frontMatter:()=>s,metadata:()=>p,toc:()=>u});var r=n(58168),a=n(98587),o=(n(96540),n(15680)),i=["components"],s={id:"multi-run",title:"Multi-run",sidebar_label:"Multi-run"},l=void 0,p={unversionedId:"tutorials/basic/running_your_app/multi-run",id:"version-1.1/tutorials/basic/running_your_app/multi-run",title:"Multi-run",description:"Sometimes you want to run the same application with multiple different configurations.",source:"@site/versioned_docs/version-1.1/tutorials/basic/running_your_app/2_multirun.md",sourceDirName:"tutorials/basic/running_your_app",slug:"/tutorials/basic/running_your_app/multi-run",permalink:"/docs/1.1/tutorials/basic/running_your_app/multi-run",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/tutorials/basic/running_your_app/2_multirun.md",tags:[],version:"1.1",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:2,frontMatter:{id:"multi-run",title:"Multi-run",sidebar_label:"Multi-run"},sidebar:"version-1.1/docs",previous:{title:"Putting it all together",permalink:"/docs/1.1/tutorials/basic/your_first_app/composition"},next:{title:"Output/Working directory",permalink:"/docs/1.1/tutorials/basic/running_your_app/working_directory"}},u=[{value:"Additional sweep types",id:"additional-sweep-types",children:[],level:3},{value:"Sweeper",id:"sweeper",children:[],level:3},{value:"Launcher",id:"launcher",children:[],level:3}],c={toc:u};function d(e){var t=e.components,n=(0,a.A)(e,i);return(0,o.mdx)("wrapper",(0,r.A)({},c,n,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"Sometimes you want to run the same application with multiple different configurations.",(0,o.mdx)("br",{parentName:"p"}),"\n","E.g. running a performance test on each of the databases with each of the schemas."),(0,o.mdx)("p",null,"Use the ",(0,o.mdx)("inlineCode",{parentName:"p"},"--multirun")," (",(0,o.mdx)("inlineCode",{parentName:"p"},"-m"),") flag and pass a comma separated list specifying the values for each dimension you want to sweep."),(0,o.mdx)("p",null,"The following sweeps over all combinations of the dbs and schemas."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="$ python my_app.py -m db=mysql,postgresql schema=warehouse,support,school"',title:'"$',python:!0,"my_app.py":!0,"-m":!0,db:"mysql,postgresql",schema:'warehouse,support,school"'},"[2021-01-20 17:25:03,317][HYDRA] Launching 6 jobs locally\n[2021-01-20 17:25:03,318][HYDRA] #0 : db=mysql schema=warehouse\n[2021-01-20 17:25:03,458][HYDRA] #1 : db=mysql schema=support\n[2021-01-20 17:25:03,602][HYDRA] #2 : db=mysql schema=school\n[2021-01-20 17:25:03,755][HYDRA] #3 : db=postgresql schema=warehouse\n[2021-01-20 17:25:03,895][HYDRA] #4 : db=postgresql schema=support\n[2021-01-20 17:25:04,040][HYDRA] #5 : db=postgresql schema=school\n")),(0,o.mdx)("p",null,"The printed configurations have been omitted for brevity."),(0,o.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,o.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,o.mdx)("h5",{parentName:"div"},(0,o.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,o.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,o.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,o.mdx)("div",{parentName:"div",className:"admonition-content"},(0,o.mdx)("p",{parentName:"div"},"Hydra composes configs lazily at job launching time. If you change code or configs after launching a job/sweep, the final\ncomposed configs might be impacted."))),(0,o.mdx)("h3",{id:"additional-sweep-types"},"Additional sweep types"),(0,o.mdx)("p",null,"Hydra supports other kinds of sweeps, e.g:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},"x=range(1,10) # 1-9\nschema=glob(*) # warehouse,support,school\nschema=glob(*,exclude=w*) # support,school\n")),(0,o.mdx)("p",null,"See the ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.1/advanced/override_grammar/extended"},"Extended Override syntax")," for details."),(0,o.mdx)("h3",{id:"sweeper"},"Sweeper"),(0,o.mdx)("p",null,"The default sweeping logic is built into Hydra. Additional sweepers are available as plugins.\nFor example, the ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.1/plugins/ax_sweeper"},"Ax Sweeper")," can automatically find the best parameter combination!"),(0,o.mdx)("h3",{id:"launcher"},"Launcher"),(0,o.mdx)("p",null,"By default, Hydra runs your multi-run jobs locally and serially.\nOther launchers are available as plugins for launching in parallel and on different clusters. For example, the ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.1/plugins/joblib_launcher"},"JobLib Launcher"),"\ncan execute the different parameter combinations in parallel on your local machine using multi-processing."))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/213609f5.73aa271a.js b/assets/js/213609f5.73aa271a.js new file mode 100644 index 0000000000..656043a8f3 --- /dev/null +++ b/assets/js/213609f5.73aa271a.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3605],{15680:(e,r,t)=>{t.r(r),t.d(r,{MDXContext:()=>c,MDXProvider:()=>l,mdx:()=>m,useMDXComponents:()=>u,withMDXComponents:()=>p});var n=t(96540);function o(e,r,t){return r in e?Object.defineProperty(e,r,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[r]=t,e}function i(){return i=Object.assign||function(e){for(var r=1;r=0||(o[t]=e[t]);return o}(e,r);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(o[t]=e[t])}return o}var c=n.createContext({}),p=function(e){return function(r){var t=u(r.components);return n.createElement(e,i({},r,{components:t}))}},u=function(e){var r=n.useContext(c),t=r;return e&&(t="function"==typeof e?e(r):d(d({},r),e)),t},l=function(e){var r=u(e.components);return n.createElement(c.Provider,{value:r},e.children)},h={inlineCode:"code",wrapper:function(e){var r=e.children;return n.createElement(n.Fragment,{},r)}},g=n.forwardRef((function(e,r){var t=e.components,o=e.mdxType,i=e.originalType,a=e.parentName,c=s(e,["components","mdxType","originalType","parentName"]),p=u(t),l=o,g=p["".concat(a,".").concat(l)]||p[l]||h[l]||i;return t?n.createElement(g,d(d({ref:r},c),{},{components:t})):n.createElement(g,d({ref:r},c))}));function m(e,r){var t=arguments,o=r&&r.mdxType;if("string"==typeof e||o){var i=t.length,a=new Array(i);a[0]=g;var d={};for(var s in r)hasOwnProperty.call(r,s)&&(d[s]=r[s]);d.originalType=e,d.mdxType="string"==typeof e?e:o,a[1]=d;for(var c=2;c{t.r(r),t.d(r,{contentTitle:()=>s,default:()=>l,frontMatter:()=>d,metadata:()=>c,toc:()=>p});var n=t(58168),o=t(98587),i=(t(96540),t(15680)),a=["components"],d={id:"changes_to_job_working_dir",title:"Changes to job's runtime working directory",hide_title:!0},s=void 0,c={unversionedId:"upgrades/1.1_to_1.2/changes_to_job_working_dir",id:"version-1.3/upgrades/1.1_to_1.2/changes_to_job_working_dir",title:"Changes to job's runtime working directory",description:"Hydra 1.2 introduces hydra.job.chdir. This config allows users to specify whether Hydra should change the runtime working",source:"@site/versioned_docs/version-1.3/upgrades/1.1_to_1.2/changes_to_job_working_dir.md",sourceDirName:"upgrades/1.1_to_1.2",slug:"/upgrades/1.1_to_1.2/changes_to_job_working_dir",permalink:"/docs/1.3/upgrades/1.1_to_1.2/changes_to_job_working_dir",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/upgrades/1.1_to_1.2/changes_to_job_working_dir.md",tags:[],version:"1.3",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"changes_to_job_working_dir",title:"Changes to job's runtime working directory",hide_title:!0},sidebar:"docs",previous:{title:"Changes to @hydra.main() and hydra.initialize()",permalink:"/docs/1.3/upgrades/1.1_to_1.2/changes_to_hydra_main_config_path"},next:{title:"Changes to configuring sweeper's search space",permalink:"/docs/1.3/upgrades/1.1_to_1.2/changes_to_sweeper_config"}},p=[],u={toc:p};function l(e){var r=e.components,t=(0,o.A)(e,a);return(0,i.mdx)("wrapper",(0,n.A)({},u,t,{components:r,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Hydra 1.2 introduces ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir"),". This config allows users to specify whether Hydra should change the runtime working\ndirectory to the job's output directory.\n",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir")," will default to ",(0,i.mdx)("inlineCode",{parentName:"p"},"False"),' if version_base is set to >= "1.2" (or None),\nor otherwise will use the old behavior and default to ',(0,i.mdx)("inlineCode",{parentName:"p"},"True"),", with a warning being issued if ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir")," is not set."),(0,i.mdx)("p",null,"If you want to keep the old Hydra behavior, please set ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir=True")," explicitly for your application."),(0,i.mdx)("p",null,"For more information about ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir"),",\nsee ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.3/tutorials/basic/running_your_app/working_directory#disable-changing-current-working-dir-to-jobs-output-dir"},"Output/Working directory"),"\nand ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.3/configure_hydra/job#hydrajobchdir"},"Job Configuration - hydra.job.chdir"),"."))}l.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/213609f5.cf59fd81.js b/assets/js/213609f5.cf59fd81.js deleted file mode 100644 index f8aab9d111..0000000000 --- a/assets/js/213609f5.cf59fd81.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3605],{15680:(e,r,t)=>{t.r(r),t.d(r,{MDXContext:()=>c,MDXProvider:()=>l,mdx:()=>m,useMDXComponents:()=>u,withMDXComponents:()=>p});var n=t(96540);function o(e,r,t){return r in e?Object.defineProperty(e,r,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[r]=t,e}function i(){return i=Object.assign||function(e){for(var r=1;r=0||(o[t]=e[t]);return o}(e,r);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(o[t]=e[t])}return o}var c=n.createContext({}),p=function(e){return function(r){var t=u(r.components);return n.createElement(e,i({},r,{components:t}))}},u=function(e){var r=n.useContext(c),t=r;return e&&(t="function"==typeof e?e(r):d(d({},r),e)),t},l=function(e){var r=u(e.components);return n.createElement(c.Provider,{value:r},e.children)},h={inlineCode:"code",wrapper:function(e){var r=e.children;return n.createElement(n.Fragment,{},r)}},g=n.forwardRef((function(e,r){var t=e.components,o=e.mdxType,i=e.originalType,a=e.parentName,c=s(e,["components","mdxType","originalType","parentName"]),p=u(t),l=o,g=p["".concat(a,".").concat(l)]||p[l]||h[l]||i;return t?n.createElement(g,d(d({ref:r},c),{},{components:t})):n.createElement(g,d({ref:r},c))}));function m(e,r){var t=arguments,o=r&&r.mdxType;if("string"==typeof e||o){var i=t.length,a=new Array(i);a[0]=g;var d={};for(var s in r)hasOwnProperty.call(r,s)&&(d[s]=r[s]);d.originalType=e,d.mdxType="string"==typeof e?e:o,a[1]=d;for(var c=2;c{t.r(r),t.d(r,{contentTitle:()=>s,default:()=>l,frontMatter:()=>d,metadata:()=>c,toc:()=>p});var n=t(58168),o=t(98587),i=(t(96540),t(15680)),a=["components"],d={id:"changes_to_job_working_dir",title:"Changes to job's runtime working directory",hide_title:!0},s=void 0,c={unversionedId:"upgrades/1.1_to_1.2/changes_to_job_working_dir",id:"version-1.3/upgrades/1.1_to_1.2/changes_to_job_working_dir",title:"Changes to job's runtime working directory",description:"Hydra 1.2 introduces hydra.job.chdir. This config allows users to specify whether Hydra should change the runtime working",source:"@site/versioned_docs/version-1.3/upgrades/1.1_to_1.2/changes_to_job_working_dir.md",sourceDirName:"upgrades/1.1_to_1.2",slug:"/upgrades/1.1_to_1.2/changes_to_job_working_dir",permalink:"/docs/1.3/upgrades/1.1_to_1.2/changes_to_job_working_dir",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/upgrades/1.1_to_1.2/changes_to_job_working_dir.md",tags:[],version:"1.3",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"changes_to_job_working_dir",title:"Changes to job's runtime working directory",hide_title:!0},sidebar:"docs",previous:{title:"Changes to @hydra.main() and hydra.initialize()",permalink:"/docs/1.3/upgrades/1.1_to_1.2/changes_to_hydra_main_config_path"},next:{title:"Changes to configuring sweeper's search space",permalink:"/docs/1.3/upgrades/1.1_to_1.2/changes_to_sweeper_config"}},p=[],u={toc:p};function l(e){var r=e.components,t=(0,o.A)(e,a);return(0,i.mdx)("wrapper",(0,n.A)({},u,t,{components:r,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Hydra 1.2 introduces ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir"),". This config allows users to specify whether Hydra should change the runtime working\ndirectory to the job's output directory.\n",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir")," will default to ",(0,i.mdx)("inlineCode",{parentName:"p"},"False"),' if version_base is set to >= "1.2" (or None),\nor otherwise will use the old behavior and default to ',(0,i.mdx)("inlineCode",{parentName:"p"},"True"),", with a warning being issued if ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir")," is not set."),(0,i.mdx)("p",null,"If you want to keep the old Hydra behavior, please set ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir=True")," explicitly for your application."),(0,i.mdx)("p",null,"For more information about ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir"),",\nsee ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.3/tutorials/basic/running_your_app/working_directory#disable-changing-current-working-dir-to-jobs-output-dir"},"Output/Working directory"),"\nand ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.3/configure_hydra/job#hydrajobchdir"},"Job Configuration - hydra.job.chdir"),"."))}l.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/215ac4d9.17d9b8c7.js b/assets/js/215ac4d9.17d9b8c7.js deleted file mode 100644 index b1b7d66474..0000000000 --- a/assets/js/215ac4d9.17d9b8c7.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[2590],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>c,MDXProvider:()=>p,mdx:()=>y,useMDXComponents:()=>u,withMDXComponents:()=>m});var r=n(96540);function a(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(a[n]=e[n]);return a}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(a[n]=e[n])}return a}var c=r.createContext({}),m=function(e){return function(t){var n=u(t.components);return r.createElement(e,o({},t,{components:n}))}},u=function(e){var t=r.useContext(c),n=t;return e&&(n="function"==typeof e?e(t):s(s({},t),e)),n},p=function(e){var t=u(e.components);return r.createElement(c.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},f=r.forwardRef((function(e,t){var n=e.components,a=e.mdxType,o=e.originalType,i=e.parentName,c=l(e,["components","mdxType","originalType","parentName"]),m=u(n),p=a,f=m["".concat(i,".").concat(p)]||m[p]||d[p]||o;return n?r.createElement(f,s(s({ref:t},c),{},{components:n})):r.createElement(f,s({ref:t},c))}));function y(e,t){var n=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var o=n.length,i=new Array(o);i[0]=f;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s.mdxType="string"==typeof e?e:a,i[1]=s;for(var c=2;c{n.d(t,{A:()=>l,C:()=>c});var r=n(58168),a=n(96540),o=n(75489),i=n(44586),s=n(74098);function l(e){return a.createElement(o.default,(0,r.A)({},e,{to:(t=e.to,l=(0,s.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==l?void 0:l.name)?n:"current"]+t),target:"_blank"}));var t,n,l}function c(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return a.createElement(l,e,a.createElement("span",null,"\xa0"),a.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},99849:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>c,default:()=>d,frontMatter:()=>l,metadata:()=>m,toc:()=>u});var r=n(58168),a=n(98587),o=(n(96540),n(15680)),i=n(49595),s=["components"],l={id:"composition",title:"Putting it all together"},c=void 0,m={unversionedId:"tutorials/basic/your_first_app/composition",id:"tutorials/basic/your_first_app/composition",title:"Putting it all together",description:"As software gets more complex, we resort to modularity and composition to keep it manageable.",source:"@site/docs/tutorials/basic/your_first_app/6_composition.md",sourceDirName:"tutorials/basic/your_first_app",slug:"/tutorials/basic/your_first_app/composition",permalink:"/docs/tutorials/basic/your_first_app/composition",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/tutorials/basic/your_first_app/6_composition.md",tags:[],version:"current",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:6,frontMatter:{id:"composition",title:"Putting it all together"},sidebar:"docs",previous:{title:"Selecting default configs",permalink:"/docs/tutorials/basic/your_first_app/defaults"},next:{title:"Multi-run",permalink:"/docs/tutorials/basic/running_your_app/multi-run"}},u=[{value:"Summary",id:"summary",children:[],level:3}],p={toc:u};function d(e){var t=e.components,n=(0,a.A)(e,s);return(0,o.mdx)("wrapper",(0,r.A)({},p,n,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)(i.C,{to:"examples/tutorials/basic/your_first_hydra_app/6_composition",mdxType:"ExampleGithubLink"}),(0,o.mdx)("p",null,"As software gets more complex, we resort to modularity and composition to keep it manageable.\nWe can do the same with configs. Suppose we want our working example to support multiple databases, with\nmultiple schemas per database, and different UIs. We wouldn't write a separate class\nfor each permutation of db, schema and UI, so we shouldn't write separate configs either. We use\nthe same solution in configuration as in writing the underlying software: composition. "),(0,o.mdx)("p",null,"To do this in Hydra, we first add a ",(0,o.mdx)("inlineCode",{parentName:"p"},"schema")," and a ",(0,o.mdx)("inlineCode",{parentName:"p"},"ui")," config group:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Directory layout"',title:'"Directory','layout"':!0},"\u251c\u2500\u2500 conf\n\u2502 \u251c\u2500\u2500 config.yaml\n\u2502 \u251c\u2500\u2500 db\n\u2502 \u2502 \u251c\u2500\u2500 mysql.yaml\n\u2502 \u2502 \u2514\u2500\u2500 postgresql.yaml\n\u2502 \u251c\u2500\u2500 schema\n\u2502 \u2502 \u251c\u2500\u2500 school.yaml\n\u2502 \u2502 \u251c\u2500\u2500 support.yaml\n\u2502 \u2502 \u2514\u2500\u2500 warehouse.yaml\n\u2502 \u2514\u2500\u2500 ui\n\u2502 \u251c\u2500\u2500 full.yaml\n\u2502 \u2514\u2500\u2500 view.yaml\n\u2514\u2500\u2500 my_app.py\n")),(0,o.mdx)("p",null,"With these configs, we already have 12 possible combinations. Without composition, we would need 12 separate configs.\nA single change, such as renaming ",(0,o.mdx)("inlineCode",{parentName:"p"},"db.user")," to ",(0,o.mdx)("inlineCode",{parentName:"p"},"db.username"),", requires editing all 12 of them.\nThis is a maintenance nightmare."),(0,o.mdx)("p",null,"Composition can come to the rescue.\nInstead of creating 12 different config files, that fully specify each\nconfig, create a single config that specifies the different configuration dimensions, and the default for each."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - db: mysql\n - ui: full\n - schema: school\n")),(0,o.mdx)("p",null,"The resulting configuration is a composition of the ",(0,o.mdx)("em",{parentName:"p"},"mysql")," database, the ",(0,o.mdx)("em",{parentName:"p"},"full")," ui, and the ",(0,o.mdx)("em",{parentName:"p"},"school")," schema\n(which we are seeing for the first time here):"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py\ndb:\n driver: mysql\n user: omry\n pass: secret\nui:\n windows:\n create_db: true\n view: true\nschema:\n database: school\n tables:\n - name: students\n fields:\n - name: string\n - class: int\n - name: exams\n fields:\n - profession: string\n - time: data\n - class: int\n")),(0,o.mdx)("p",null,"Stay tuned to see how to run all of the combinations automatically (",(0,o.mdx)("a",{parentName:"p",href:"/docs/tutorials/basic/running_your_app/multi-run"},"Multi-run"),")."),(0,o.mdx)("h3",{id:"summary"},"Summary"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"The addition of each new db, schema, or ui only requires a single file."),(0,o.mdx)("li",{parentName:"ul"},"Each config group can have a default specified in the Defaults List."),(0,o.mdx)("li",{parentName:"ul"},"Any combination can be composed by selecting the desired option from each config group in the\nDefaults List or the command line.")))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/215ac4d9.c790b40b.js b/assets/js/215ac4d9.c790b40b.js new file mode 100644 index 0000000000..0be8f2e2a5 --- /dev/null +++ b/assets/js/215ac4d9.c790b40b.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[2590],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>c,MDXProvider:()=>p,mdx:()=>y,useMDXComponents:()=>u,withMDXComponents:()=>m});var r=n(96540);function a(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(a[n]=e[n]);return a}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(a[n]=e[n])}return a}var c=r.createContext({}),m=function(e){return function(t){var n=u(t.components);return r.createElement(e,o({},t,{components:n}))}},u=function(e){var t=r.useContext(c),n=t;return e&&(n="function"==typeof e?e(t):s(s({},t),e)),n},p=function(e){var t=u(e.components);return r.createElement(c.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},f=r.forwardRef((function(e,t){var n=e.components,a=e.mdxType,o=e.originalType,i=e.parentName,c=l(e,["components","mdxType","originalType","parentName"]),m=u(n),p=a,f=m["".concat(i,".").concat(p)]||m[p]||d[p]||o;return n?r.createElement(f,s(s({ref:t},c),{},{components:n})):r.createElement(f,s({ref:t},c))}));function y(e,t){var n=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var o=n.length,i=new Array(o);i[0]=f;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s.mdxType="string"==typeof e?e:a,i[1]=s;for(var c=2;c{n.d(t,{A:()=>l,C:()=>c});var r=n(58168),a=n(96540),o=n(75489),i=n(44586),s=n(74098);function l(e){return a.createElement(o.default,(0,r.A)({},e,{to:(t=e.to,l=(0,s.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==l?void 0:l.name)?n:"current"]+t),target:"_blank"}));var t,n,l}function c(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return a.createElement(l,e,a.createElement("span",null,"\xa0"),a.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},99849:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>c,default:()=>d,frontMatter:()=>l,metadata:()=>m,toc:()=>u});var r=n(58168),a=n(98587),o=(n(96540),n(15680)),i=n(49595),s=["components"],l={id:"composition",title:"Putting it all together"},c=void 0,m={unversionedId:"tutorials/basic/your_first_app/composition",id:"tutorials/basic/your_first_app/composition",title:"Putting it all together",description:"As software gets more complex, we resort to modularity and composition to keep it manageable.",source:"@site/docs/tutorials/basic/your_first_app/6_composition.md",sourceDirName:"tutorials/basic/your_first_app",slug:"/tutorials/basic/your_first_app/composition",permalink:"/docs/tutorials/basic/your_first_app/composition",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/tutorials/basic/your_first_app/6_composition.md",tags:[],version:"current",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:6,frontMatter:{id:"composition",title:"Putting it all together"},sidebar:"docs",previous:{title:"Selecting default configs",permalink:"/docs/tutorials/basic/your_first_app/defaults"},next:{title:"Multi-run",permalink:"/docs/tutorials/basic/running_your_app/multi-run"}},u=[{value:"Summary",id:"summary",children:[],level:3}],p={toc:u};function d(e){var t=e.components,n=(0,a.A)(e,s);return(0,o.mdx)("wrapper",(0,r.A)({},p,n,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)(i.C,{to:"examples/tutorials/basic/your_first_hydra_app/6_composition",mdxType:"ExampleGithubLink"}),(0,o.mdx)("p",null,"As software gets more complex, we resort to modularity and composition to keep it manageable.\nWe can do the same with configs. Suppose we want our working example to support multiple databases, with\nmultiple schemas per database, and different UIs. We wouldn't write a separate class\nfor each permutation of db, schema and UI, so we shouldn't write separate configs either. We use\nthe same solution in configuration as in writing the underlying software: composition. "),(0,o.mdx)("p",null,"To do this in Hydra, we first add a ",(0,o.mdx)("inlineCode",{parentName:"p"},"schema")," and a ",(0,o.mdx)("inlineCode",{parentName:"p"},"ui")," config group:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Directory layout"',title:'"Directory','layout"':!0},"\u251c\u2500\u2500 conf\n\u2502 \u251c\u2500\u2500 config.yaml\n\u2502 \u251c\u2500\u2500 db\n\u2502 \u2502 \u251c\u2500\u2500 mysql.yaml\n\u2502 \u2502 \u2514\u2500\u2500 postgresql.yaml\n\u2502 \u251c\u2500\u2500 schema\n\u2502 \u2502 \u251c\u2500\u2500 school.yaml\n\u2502 \u2502 \u251c\u2500\u2500 support.yaml\n\u2502 \u2502 \u2514\u2500\u2500 warehouse.yaml\n\u2502 \u2514\u2500\u2500 ui\n\u2502 \u251c\u2500\u2500 full.yaml\n\u2502 \u2514\u2500\u2500 view.yaml\n\u2514\u2500\u2500 my_app.py\n")),(0,o.mdx)("p",null,"With these configs, we already have 12 possible combinations. Without composition, we would need 12 separate configs.\nA single change, such as renaming ",(0,o.mdx)("inlineCode",{parentName:"p"},"db.user")," to ",(0,o.mdx)("inlineCode",{parentName:"p"},"db.username"),", requires editing all 12 of them.\nThis is a maintenance nightmare."),(0,o.mdx)("p",null,"Composition can come to the rescue.\nInstead of creating 12 different config files, that fully specify each\nconfig, create a single config that specifies the different configuration dimensions, and the default for each."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - db: mysql\n - ui: full\n - schema: school\n")),(0,o.mdx)("p",null,"The resulting configuration is a composition of the ",(0,o.mdx)("em",{parentName:"p"},"mysql")," database, the ",(0,o.mdx)("em",{parentName:"p"},"full")," ui, and the ",(0,o.mdx)("em",{parentName:"p"},"school")," schema\n(which we are seeing for the first time here):"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py\ndb:\n driver: mysql\n user: omry\n pass: secret\nui:\n windows:\n create_db: true\n view: true\nschema:\n database: school\n tables:\n - name: students\n fields:\n - name: string\n - class: int\n - name: exams\n fields:\n - profession: string\n - time: data\n - class: int\n")),(0,o.mdx)("p",null,"Stay tuned to see how to run all of the combinations automatically (",(0,o.mdx)("a",{parentName:"p",href:"/docs/tutorials/basic/running_your_app/multi-run"},"Multi-run"),")."),(0,o.mdx)("h3",{id:"summary"},"Summary"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"The addition of each new db, schema, or ui only requires a single file."),(0,o.mdx)("li",{parentName:"ul"},"Each config group can have a default specified in the Defaults List."),(0,o.mdx)("li",{parentName:"ul"},"Any combination can be composed by selecting the desired option from each config group in the\nDefaults List or the command line.")))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/215cc2c0.a5118eb2.js b/assets/js/215cc2c0.a5118eb2.js deleted file mode 100644 index 8cc2b5aebe..0000000000 --- a/assets/js/215cc2c0.a5118eb2.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[8174],{15680:(e,a,t)=>{t.r(a),t.d(a,{MDXContext:()=>m,MDXProvider:()=>p,mdx:()=>h,useMDXComponents:()=>c,withMDXComponents:()=>s});var n=t(96540);function r(e,a,t){return a in e?Object.defineProperty(e,a,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[a]=t,e}function o(){return o=Object.assign||function(e){for(var a=1;a=0||(r[t]=e[t]);return r}(e,a);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(r[t]=e[t])}return r}var m=n.createContext({}),s=function(e){return function(a){var t=c(a.components);return n.createElement(e,o({},a,{components:t}))}},c=function(e){var a=n.useContext(m),t=a;return e&&(t="function"==typeof e?e(a):l(l({},a),e)),t},p=function(e){var a=c(e.components);return n.createElement(m.Provider,{value:a},e.children)},u={inlineCode:"code",wrapper:function(e){var a=e.children;return n.createElement(n.Fragment,{},a)}},g=n.forwardRef((function(e,a){var t=e.components,r=e.mdxType,o=e.originalType,i=e.parentName,m=d(e,["components","mdxType","originalType","parentName"]),s=c(t),p=r,g=s["".concat(i,".").concat(p)]||s[p]||u[p]||o;return t?n.createElement(g,l(l({ref:a},m),{},{components:t})):n.createElement(g,l({ref:a},m))}));function h(e,a){var t=arguments,r=a&&a.mdxType;if("string"==typeof e||r){var o=t.length,i=new Array(o);i[0]=g;var l={};for(var d in a)hasOwnProperty.call(a,d)&&(l[d]=a[d]);l.originalType=e,l.mdxType="string"==typeof e?e:r,i[1]=l;for(var m=2;m{t.r(a),t.d(a,{contentTitle:()=>d,default:()=>p,frontMatter:()=>l,metadata:()=>m,toc:()=>s});var n=t(58168),r=t(98587),o=(t(96540),t(15680)),i=["components"],l={id:"changes_to_package_header",title:"Changes to Package Header"},d=void 0,m={unversionedId:"upgrades/1.0_to_1.1/changes_to_package_header",id:"version-1.3/upgrades/1.0_to_1.1/changes_to_package_header",title:"Changes to Package Header",description:"Hydra 1.0 introduced the package header and required everyone to specify it in their configs.",source:"@site/versioned_docs/version-1.3/upgrades/1.0_to_1.1/changes_to_package_header.md",sourceDirName:"upgrades/1.0_to_1.1",slug:"/upgrades/1.0_to_1.1/changes_to_package_header",permalink:"/docs/1.3/upgrades/1.0_to_1.1/changes_to_package_header",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/upgrades/1.0_to_1.1/changes_to_package_header.md",tags:[],version:"1.3",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"changes_to_package_header",title:"Changes to Package Header"},sidebar:"docs",previous:{title:"Defaults List interpolation",permalink:"/docs/1.3/upgrades/1.0_to_1.1/defaults_list_interpolation"},next:{title:"Automatic schema-matching",permalink:"/docs/1.3/upgrades/1.0_to_1.1/automatic_schema_matching"}},s=[{value:"Migration",id:"migration",children:[],level:3},{value:"Compatibility with both Hydra 1.0 and 1.1",id:"compatibility-with-both-hydra-10-and-11",children:[],level:3}],c={toc:s};function p(e){var a=e.components,t=(0,r.A)(e,i);return(0,o.mdx)("wrapper",(0,n.A)({},c,t,{components:a,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"Hydra 1.0 introduced the package header and required everyone to specify it in their configs.\nThis was done to facilitate a transition from a model where the packages are global\nto a model where - by default - package are derived from the config group."),(0,o.mdx)("p",null,"e.g: Change of the default package for ",(0,o.mdx)("inlineCode",{parentName:"p"},"server/db/mysql.yaml")," from ",(0,o.mdx)("inlineCode",{parentName:"p"},"_global_")," to ",(0,o.mdx)("inlineCode",{parentName:"p"},"server.db"),"."),(0,o.mdx)("p",null,"Hydra 1.1 completes this transition. "),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"If a package header is not specified, the config will have the default package as described above."),(0,o.mdx)("li",{parentName:"ul"},"_","group","_"," and ","_","name","_"," in package header are deprecated (You can still use a literal package header).")),(0,o.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,o.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,o.mdx)("h5",{parentName:"div"},(0,o.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,o.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,o.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"info")),(0,o.mdx)("div",{parentName:"div",className:"admonition-content"},(0,o.mdx)("p",{parentName:"div"},"Another important change in Hydra 1.1 is the\n",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.3/upgrades/1.0_to_1.1/default_composition_order"},"Changes to default composition order"),"."))),(0,o.mdx)("h3",{id:"migration"},"Migration"),(0,o.mdx)("p",null,"If your header is ",(0,o.mdx)("inlineCode",{parentName:"p"},"# @package _group_"),", remove the header."),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml in Hydra 1.0"',title:'"db/mysql.yaml',in:!0,Hydra:!0,'1.0"':!0},"# @package _group_\nhost: localhost\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml in Hydra 1.1"',title:'"db/mysql.yaml',in:!0,Hydra:!0,'1.1"':!0},"host: localhost\n\n")))),(0,o.mdx)("p",null,"If your header is using ",(0,o.mdx)("inlineCode",{parentName:"p"},"_group_")," or ",(0,o.mdx)("inlineCode",{parentName:"p"},"_name_")," to specify a package other than the default package,\nSpecify the literal package:"),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml in Hydra 1.0"',title:'"db/mysql.yaml',in:!0,Hydra:!0,'1.0"':!0},"# @package _group_._name_\nhost: localhost\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml in Hydra 1.1"',title:'"db/mysql.yaml',in:!0,Hydra:!0,'1.1"':!0},"# @package db.mysql\nhost: localhost\n")))),(0,o.mdx)("h3",{id:"compatibility-with-both-hydra-10-and-11"},"Compatibility with both Hydra 1.0 and 1.1"),(0,o.mdx)("p",null,"If your configs should be compatible with both Hydra 1.0 and Hydra 1.1, use literal package headers."),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml in Hydra 1.0"',title:'"db/mysql.yaml',in:!0,Hydra:!0,'1.0"':!0},"# @package _group_\nhost: localhost\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml in Hydra 1.1"',title:'"db/mysql.yaml',in:!0,Hydra:!0,'1.1"':!0},"# @package db\nhost: localhost\n")))))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/215cc2c0.e31c40ad.js b/assets/js/215cc2c0.e31c40ad.js new file mode 100644 index 0000000000..09b334bffb --- /dev/null +++ b/assets/js/215cc2c0.e31c40ad.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[8174],{15680:(e,a,t)=>{t.r(a),t.d(a,{MDXContext:()=>m,MDXProvider:()=>p,mdx:()=>h,useMDXComponents:()=>c,withMDXComponents:()=>s});var r=t(96540);function n(e,a,t){return a in e?Object.defineProperty(e,a,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[a]=t,e}function o(){return o=Object.assign||function(e){for(var a=1;a=0||(n[t]=e[t]);return n}(e,a);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(n[t]=e[t])}return n}var m=r.createContext({}),s=function(e){return function(a){var t=c(a.components);return r.createElement(e,o({},a,{components:t}))}},c=function(e){var a=r.useContext(m),t=a;return e&&(t="function"==typeof e?e(a):d(d({},a),e)),t},p=function(e){var a=c(e.components);return r.createElement(m.Provider,{value:a},e.children)},u={inlineCode:"code",wrapper:function(e){var a=e.children;return r.createElement(r.Fragment,{},a)}},g=r.forwardRef((function(e,a){var t=e.components,n=e.mdxType,o=e.originalType,i=e.parentName,m=l(e,["components","mdxType","originalType","parentName"]),s=c(t),p=n,g=s["".concat(i,".").concat(p)]||s[p]||u[p]||o;return t?r.createElement(g,d(d({ref:a},m),{},{components:t})):r.createElement(g,d({ref:a},m))}));function h(e,a){var t=arguments,n=a&&a.mdxType;if("string"==typeof e||n){var o=t.length,i=new Array(o);i[0]=g;var d={};for(var l in a)hasOwnProperty.call(a,l)&&(d[l]=a[l]);d.originalType=e,d.mdxType="string"==typeof e?e:n,i[1]=d;for(var m=2;m{t.r(a),t.d(a,{contentTitle:()=>l,default:()=>p,frontMatter:()=>d,metadata:()=>m,toc:()=>s});var r=t(58168),n=t(98587),o=(t(96540),t(15680)),i=["components"],d={id:"changes_to_package_header",title:"Changes to Package Header"},l=void 0,m={unversionedId:"upgrades/1.0_to_1.1/changes_to_package_header",id:"version-1.3/upgrades/1.0_to_1.1/changes_to_package_header",title:"Changes to Package Header",description:"Hydra 1.0 introduced the package header and required everyone to specify it in their configs.",source:"@site/versioned_docs/version-1.3/upgrades/1.0_to_1.1/changes_to_package_header.md",sourceDirName:"upgrades/1.0_to_1.1",slug:"/upgrades/1.0_to_1.1/changes_to_package_header",permalink:"/docs/1.3/upgrades/1.0_to_1.1/changes_to_package_header",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/upgrades/1.0_to_1.1/changes_to_package_header.md",tags:[],version:"1.3",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"changes_to_package_header",title:"Changes to Package Header"},sidebar:"docs",previous:{title:"Defaults List interpolation",permalink:"/docs/1.3/upgrades/1.0_to_1.1/defaults_list_interpolation"},next:{title:"Automatic schema-matching",permalink:"/docs/1.3/upgrades/1.0_to_1.1/automatic_schema_matching"}},s=[{value:"Migration",id:"migration",children:[],level:3},{value:"Compatibility with both Hydra 1.0 and 1.1",id:"compatibility-with-both-hydra-10-and-11",children:[],level:3}],c={toc:s};function p(e){var a=e.components,t=(0,n.A)(e,i);return(0,o.mdx)("wrapper",(0,r.A)({},c,t,{components:a,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"Hydra 1.0 introduced the package header and required everyone to specify it in their configs.\nThis was done to facilitate a transition from a model where the packages are global\nto a model where - by default - package are derived from the config group."),(0,o.mdx)("p",null,"e.g: Change of the default package for ",(0,o.mdx)("inlineCode",{parentName:"p"},"server/db/mysql.yaml")," from ",(0,o.mdx)("inlineCode",{parentName:"p"},"_global_")," to ",(0,o.mdx)("inlineCode",{parentName:"p"},"server.db"),"."),(0,o.mdx)("p",null,"Hydra 1.1 completes this transition. "),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"If a package header is not specified, the config will have the default package as described above."),(0,o.mdx)("li",{parentName:"ul"},"_","group","_"," and ","_","name","_"," in package header are deprecated (You can still use a literal package header).")),(0,o.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,o.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,o.mdx)("h5",{parentName:"div"},(0,o.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,o.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,o.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"info")),(0,o.mdx)("div",{parentName:"div",className:"admonition-content"},(0,o.mdx)("p",{parentName:"div"},"Another important change in Hydra 1.1 is the\n",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.3/upgrades/1.0_to_1.1/default_composition_order"},"Changes to default composition order"),"."))),(0,o.mdx)("h3",{id:"migration"},"Migration"),(0,o.mdx)("p",null,"If your header is ",(0,o.mdx)("inlineCode",{parentName:"p"},"# @package _group_"),", remove the header."),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml in Hydra 1.0"',title:'"db/mysql.yaml',in:!0,Hydra:!0,'1.0"':!0},"# @package _group_\nhost: localhost\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml in Hydra 1.1"',title:'"db/mysql.yaml',in:!0,Hydra:!0,'1.1"':!0},"host: localhost\n\n")))),(0,o.mdx)("p",null,"If your header is using ",(0,o.mdx)("inlineCode",{parentName:"p"},"_group_")," or ",(0,o.mdx)("inlineCode",{parentName:"p"},"_name_")," to specify a package other than the default package,\nSpecify the literal package:"),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml in Hydra 1.0"',title:'"db/mysql.yaml',in:!0,Hydra:!0,'1.0"':!0},"# @package _group_._name_\nhost: localhost\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml in Hydra 1.1"',title:'"db/mysql.yaml',in:!0,Hydra:!0,'1.1"':!0},"# @package db.mysql\nhost: localhost\n")))),(0,o.mdx)("h3",{id:"compatibility-with-both-hydra-10-and-11"},"Compatibility with both Hydra 1.0 and 1.1"),(0,o.mdx)("p",null,"If your configs should be compatible with both Hydra 1.0 and Hydra 1.1, use literal package headers."),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml in Hydra 1.0"',title:'"db/mysql.yaml',in:!0,Hydra:!0,'1.0"':!0},"# @package _group_\nhost: localhost\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml in Hydra 1.1"',title:'"db/mysql.yaml',in:!0,Hydra:!0,'1.1"':!0},"# @package db\nhost: localhost\n")))))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2174f925.95399bcb.js b/assets/js/2174f925.95399bcb.js deleted file mode 100644 index 199620be03..0000000000 --- a/assets/js/2174f925.95399bcb.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[1569],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>d,MDXProvider:()=>p,mdx:()=>f,useMDXComponents:()=>s,withMDXComponents:()=>c});var a=t(96540);function i(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function o(){return o=Object.assign||function(e){for(var n=1;n=0||(i[t]=e[t]);return i}(e,n);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(i[t]=e[t])}return i}var d=a.createContext({}),c=function(e){return function(n){var t=s(n.components);return a.createElement(e,o({},n,{components:t}))}},s=function(e){var n=a.useContext(d),t=n;return e&&(t="function"==typeof e?e(n):l(l({},n),e)),t},p=function(e){var n=s(e.components);return a.createElement(d.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},h=a.forwardRef((function(e,n){var t=e.components,i=e.mdxType,o=e.originalType,r=e.parentName,d=m(e,["components","mdxType","originalType","parentName"]),c=s(t),p=i,h=c["".concat(r,".").concat(p)]||c[p]||u[p]||o;return t?a.createElement(h,l(l({ref:n},d),{},{components:t})):a.createElement(h,l({ref:n},d))}));function f(e,n){var t=arguments,i=n&&n.mdxType;if("string"==typeof e||i){var o=t.length,r=new Array(o);r[0]=h;var l={};for(var m in n)hasOwnProperty.call(n,m)&&(l[m]=n[m]);l.originalType=e,l.mdxType="string"==typeof e?e:i,r[1]=l;for(var d=2;d{t.d(n,{A:()=>m,C:()=>d});var a=t(58168),i=t(96540),o=t(75489),r=t(44586),l=t(74098);function m(e){return i.createElement(o.default,(0,a.A)({},e,{to:(n=e.to,m=(0,l.useActiveVersion)(),(0,r.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==m?void 0:m.name)?t:"current"]+n),target:"_blank"}));var n,t,m}function d(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return i.createElement(m,e,i.createElement("span",null,"\xa0"),i.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},13828:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>d,default:()=>u,frontMatter:()=>m,metadata:()=>c,toc:()=>s});var a=t(58168),i=t(98587),o=(t(96540),t(15680)),r=t(49595),l=["components"],m={id:"compose_api",title:"Compose API",sidebar_label:"Compose API"},d=void 0,c={unversionedId:"advanced/compose_api",id:"version-1.1/advanced/compose_api",title:"Compose API",description:"The compose API can compose a config similarly to @hydra.main() anywhere in the code.",source:"@site/versioned_docs/version-1.1/advanced/compose_api.md",sourceDirName:"advanced",slug:"/advanced/compose_api",permalink:"/docs/1.1/advanced/compose_api",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/advanced/compose_api.md",tags:[],version:"1.1",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"compose_api",title:"Compose API",sidebar_label:"Compose API"},sidebar:"version-1.1/docs",previous:{title:"Structured Configs example",permalink:"/docs/1.1/advanced/instantiate_objects/structured_config"},next:{title:"Config Search Path",permalink:"/docs/1.1/advanced/search_path"}},s=[{value:"When to use the Compose API",id:"when-to-use-the-compose-api",children:[],level:3},{value:"Initialization methods",id:"initialization-methods",children:[],level:3},{value:"Code example",id:"code-example",children:[],level:3},{value:"API Documentation",id:"api-documentation",children:[],level:3}],p={toc:s};function u(e){var n=e.components,t=(0,i.A)(e,l);return(0,o.mdx)("wrapper",(0,a.A)({},p,t,{components:n,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"The compose API can compose a config similarly to ",(0,o.mdx)("inlineCode",{parentName:"p"},"@hydra.main()")," anywhere in the code.",(0,o.mdx)("br",{parentName:"p"}),"\n","Prior to calling compose(), you have to initialize Hydra: This can be done by using the standard ",(0,o.mdx)("inlineCode",{parentName:"p"},"@hydra.main()"),"\nor by calling one of the initialization methods listed below."),(0,o.mdx)("h3",{id:"when-to-use-the-compose-api"},"When to use the Compose API"),(0,o.mdx)("p",null,"The Compose API is useful when ",(0,o.mdx)("inlineCode",{parentName:"p"},"@hydra.main()")," is not applicable.\nFor example:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"Inside a Jupyter notebook (",(0,o.mdx)("a",{parentName:"li",href:"/docs/1.1/advanced/jupyter_notebooks"},"Example"),")"),(0,o.mdx)("li",{parentName:"ul"},"Inside a unit test (",(0,o.mdx)("a",{parentName:"li",href:"/docs/1.1/advanced/unit_testing"},"Example"),")"),(0,o.mdx)("li",{parentName:"ul"},"In parts of your application that does not have access to the command line (",(0,o.mdx)(r.A,{to:"examples/advanced/ad_hoc_composition",mdxType:"GithubLink"},"Example"),")."),(0,o.mdx)("li",{parentName:"ul"},"To compose multiple configuration objects (",(0,o.mdx)(r.A,{to:"examples/advanced/ray_example/ray_compose_example.py",mdxType:"GithubLink"},"Example with Ray"),").")),(0,o.mdx)("div",{class:"alert alert--info",role:"alert"},"Please avoid using the Compose API in cases where ",(0,o.mdx)("b",null,"@hydra.main()")," can be used. Doing so forfeits many of the benefits of Hydra (e.g., Tab completion, Multirun, Working directory management, Logging management and more)"),(0,o.mdx)("h3",{id:"initialization-methods"},"Initialization methods"),(0,o.mdx)("p",null,"There are 3 initialization methods:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"initialize()"),": Initialize with a config path relative to the caller"),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"initialize_config_module()")," : Initialize with config_module (absolute)"),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"initialize_config_dir()")," : Initialize with a config_dir on the file system (absolute)")),(0,o.mdx)("p",null,"All 3 can be used as methods or contexts.\nWhen used as methods, they are initializing Hydra globally and should only be called once.\nWhen used as contexts, they are initializing Hydra within the context can be used multiple times."),(0,o.mdx)("h3",{id:"code-example"},"Code example"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'from hydra import compose, initialize\nfrom omegaconf import OmegaConf\n\nif __name__ == "__main__":\n # context initialization\n with initialize(config_path="conf", job_name="test_app"):\n cfg = compose(config_name="config", overrides=["db=mysql", "db.user=me"])\n print(OmegaConf.to_yaml(cfg))\n\n # global initialization\n initialize(config_path="conf", job_name="test_app")\n cfg = compose(config_name="config", overrides=["db=mysql", "db.user=me"])\n print(OmegaConf.to_yaml(cfg))\n')),(0,o.mdx)("h3",{id:"api-documentation"},"API Documentation"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Compose API"',title:'"Compose','API"':!0},'def compose(\n config_name: Optional[str] = None,\n overrides: List[str] = [],\n return_hydra_config: bool = False,\n) -> DictConfig:\n """\n :param config_name: the name of the config\n (usually the file name without the .yaml extension)\n :param overrides: list of overrides for config file\n :param return_hydra_config: True to return the hydra config node in the result\n :return: the composed config\n """\n')),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Relative initialization"',title:'"Relative','initialization"':!0},'def initialize(\n config_path: Optional[str] = None,\n job_name: Optional[str] = "app",\n caller_stack_depth: int = 1,\n) -> None:\n """\n Initializes Hydra and add the config_path to the config search path.\n config_path is relative to the parent of the caller.\n Hydra detects the caller type automatically at runtime.\n\n Supported callers:\n - Python scripts\n - Python modules\n - Unit tests\n - Jupyter notebooks.\n :param config_path: path relative to the parent of the caller\n :param job_name: the value for hydra.job.name (By default it is automatically detected based on the caller)\n :param caller_stack_depth: stack depth of the caller, defaults to 1 (direct caller).\n """\n')),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Initialzing with config module"',title:'"Initialzing',with:!0,config:!0,'module"':!0},'def initialize_config_module(config_module: str, job_name: str = "app") -> None:\n """\n Initializes Hydra and add the config_module to the config search path.\n The config module must be importable (an __init__.py must exist at its top level)\n :param config_module: absolute module name, for example "foo.bar.conf".\n :param job_name: the value for hydra.job.name (default is \'app\')\n """\n')),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Initialzing with config directory"',title:'"Initialzing',with:!0,config:!0,'directory"':!0},'def initialize_config_dir(config_dir: str, job_name: str = "app") -> None:\n """\n Initializes Hydra and add an absolute config dir to the to the config search path.\n The config_dir is always a path on the file system and is must be an absolute path.\n Relative paths will result in an error.\n :param config_dir: absolute file system path\n :param job_name: the value for hydra.job.name (default is \'app\')\n """\n')))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2174f925.fab7fdf2.js b/assets/js/2174f925.fab7fdf2.js new file mode 100644 index 0000000000..273f2a28a9 --- /dev/null +++ b/assets/js/2174f925.fab7fdf2.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[1569],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>d,MDXProvider:()=>p,mdx:()=>f,useMDXComponents:()=>s,withMDXComponents:()=>c});var a=t(96540);function i(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function o(){return o=Object.assign||function(e){for(var n=1;n=0||(i[t]=e[t]);return i}(e,n);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(i[t]=e[t])}return i}var d=a.createContext({}),c=function(e){return function(n){var t=s(n.components);return a.createElement(e,o({},n,{components:t}))}},s=function(e){var n=a.useContext(d),t=n;return e&&(t="function"==typeof e?e(n):l(l({},n),e)),t},p=function(e){var n=s(e.components);return a.createElement(d.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},h=a.forwardRef((function(e,n){var t=e.components,i=e.mdxType,o=e.originalType,r=e.parentName,d=m(e,["components","mdxType","originalType","parentName"]),c=s(t),p=i,h=c["".concat(r,".").concat(p)]||c[p]||u[p]||o;return t?a.createElement(h,l(l({ref:n},d),{},{components:t})):a.createElement(h,l({ref:n},d))}));function f(e,n){var t=arguments,i=n&&n.mdxType;if("string"==typeof e||i){var o=t.length,r=new Array(o);r[0]=h;var l={};for(var m in n)hasOwnProperty.call(n,m)&&(l[m]=n[m]);l.originalType=e,l.mdxType="string"==typeof e?e:i,r[1]=l;for(var d=2;d{t.d(n,{A:()=>m,C:()=>d});var a=t(58168),i=t(96540),o=t(75489),r=t(44586),l=t(74098);function m(e){return i.createElement(o.default,(0,a.A)({},e,{to:(n=e.to,m=(0,l.useActiveVersion)(),(0,r.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==m?void 0:m.name)?t:"current"]+n),target:"_blank"}));var n,t,m}function d(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return i.createElement(m,e,i.createElement("span",null,"\xa0"),i.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},13828:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>d,default:()=>u,frontMatter:()=>m,metadata:()=>c,toc:()=>s});var a=t(58168),i=t(98587),o=(t(96540),t(15680)),r=t(49595),l=["components"],m={id:"compose_api",title:"Compose API",sidebar_label:"Compose API"},d=void 0,c={unversionedId:"advanced/compose_api",id:"version-1.1/advanced/compose_api",title:"Compose API",description:"The compose API can compose a config similarly to @hydra.main() anywhere in the code.",source:"@site/versioned_docs/version-1.1/advanced/compose_api.md",sourceDirName:"advanced",slug:"/advanced/compose_api",permalink:"/docs/1.1/advanced/compose_api",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/advanced/compose_api.md",tags:[],version:"1.1",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"compose_api",title:"Compose API",sidebar_label:"Compose API"},sidebar:"version-1.1/docs",previous:{title:"Structured Configs example",permalink:"/docs/1.1/advanced/instantiate_objects/structured_config"},next:{title:"Config Search Path",permalink:"/docs/1.1/advanced/search_path"}},s=[{value:"When to use the Compose API",id:"when-to-use-the-compose-api",children:[],level:3},{value:"Initialization methods",id:"initialization-methods",children:[],level:3},{value:"Code example",id:"code-example",children:[],level:3},{value:"API Documentation",id:"api-documentation",children:[],level:3}],p={toc:s};function u(e){var n=e.components,t=(0,i.A)(e,l);return(0,o.mdx)("wrapper",(0,a.A)({},p,t,{components:n,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"The compose API can compose a config similarly to ",(0,o.mdx)("inlineCode",{parentName:"p"},"@hydra.main()")," anywhere in the code.",(0,o.mdx)("br",{parentName:"p"}),"\n","Prior to calling compose(), you have to initialize Hydra: This can be done by using the standard ",(0,o.mdx)("inlineCode",{parentName:"p"},"@hydra.main()"),"\nor by calling one of the initialization methods listed below."),(0,o.mdx)("h3",{id:"when-to-use-the-compose-api"},"When to use the Compose API"),(0,o.mdx)("p",null,"The Compose API is useful when ",(0,o.mdx)("inlineCode",{parentName:"p"},"@hydra.main()")," is not applicable.\nFor example:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"Inside a Jupyter notebook (",(0,o.mdx)("a",{parentName:"li",href:"/docs/1.1/advanced/jupyter_notebooks"},"Example"),")"),(0,o.mdx)("li",{parentName:"ul"},"Inside a unit test (",(0,o.mdx)("a",{parentName:"li",href:"/docs/1.1/advanced/unit_testing"},"Example"),")"),(0,o.mdx)("li",{parentName:"ul"},"In parts of your application that does not have access to the command line (",(0,o.mdx)(r.A,{to:"examples/advanced/ad_hoc_composition",mdxType:"GithubLink"},"Example"),")."),(0,o.mdx)("li",{parentName:"ul"},"To compose multiple configuration objects (",(0,o.mdx)(r.A,{to:"examples/advanced/ray_example/ray_compose_example.py",mdxType:"GithubLink"},"Example with Ray"),").")),(0,o.mdx)("div",{class:"alert alert--info",role:"alert"},"Please avoid using the Compose API in cases where ",(0,o.mdx)("b",null,"@hydra.main()")," can be used. Doing so forfeits many of the benefits of Hydra (e.g., Tab completion, Multirun, Working directory management, Logging management and more)"),(0,o.mdx)("h3",{id:"initialization-methods"},"Initialization methods"),(0,o.mdx)("p",null,"There are 3 initialization methods:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"initialize()"),": Initialize with a config path relative to the caller"),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"initialize_config_module()")," : Initialize with config_module (absolute)"),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"initialize_config_dir()")," : Initialize with a config_dir on the file system (absolute)")),(0,o.mdx)("p",null,"All 3 can be used as methods or contexts.\nWhen used as methods, they are initializing Hydra globally and should only be called once.\nWhen used as contexts, they are initializing Hydra within the context can be used multiple times."),(0,o.mdx)("h3",{id:"code-example"},"Code example"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'from hydra import compose, initialize\nfrom omegaconf import OmegaConf\n\nif __name__ == "__main__":\n # context initialization\n with initialize(config_path="conf", job_name="test_app"):\n cfg = compose(config_name="config", overrides=["db=mysql", "db.user=me"])\n print(OmegaConf.to_yaml(cfg))\n\n # global initialization\n initialize(config_path="conf", job_name="test_app")\n cfg = compose(config_name="config", overrides=["db=mysql", "db.user=me"])\n print(OmegaConf.to_yaml(cfg))\n')),(0,o.mdx)("h3",{id:"api-documentation"},"API Documentation"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Compose API"',title:'"Compose','API"':!0},'def compose(\n config_name: Optional[str] = None,\n overrides: List[str] = [],\n return_hydra_config: bool = False,\n) -> DictConfig:\n """\n :param config_name: the name of the config\n (usually the file name without the .yaml extension)\n :param overrides: list of overrides for config file\n :param return_hydra_config: True to return the hydra config node in the result\n :return: the composed config\n """\n')),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Relative initialization"',title:'"Relative','initialization"':!0},'def initialize(\n config_path: Optional[str] = None,\n job_name: Optional[str] = "app",\n caller_stack_depth: int = 1,\n) -> None:\n """\n Initializes Hydra and add the config_path to the config search path.\n config_path is relative to the parent of the caller.\n Hydra detects the caller type automatically at runtime.\n\n Supported callers:\n - Python scripts\n - Python modules\n - Unit tests\n - Jupyter notebooks.\n :param config_path: path relative to the parent of the caller\n :param job_name: the value for hydra.job.name (By default it is automatically detected based on the caller)\n :param caller_stack_depth: stack depth of the caller, defaults to 1 (direct caller).\n """\n')),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Initialzing with config module"',title:'"Initialzing',with:!0,config:!0,'module"':!0},'def initialize_config_module(config_module: str, job_name: str = "app") -> None:\n """\n Initializes Hydra and add the config_module to the config search path.\n The config module must be importable (an __init__.py must exist at its top level)\n :param config_module: absolute module name, for example "foo.bar.conf".\n :param job_name: the value for hydra.job.name (default is \'app\')\n """\n')),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Initialzing with config directory"',title:'"Initialzing',with:!0,config:!0,'directory"':!0},'def initialize_config_dir(config_dir: str, job_name: str = "app") -> None:\n """\n Initializes Hydra and add an absolute config dir to the to the config search path.\n The config_dir is always a path on the file system and is must be an absolute path.\n Relative paths will result in an error.\n :param config_dir: absolute file system path\n :param job_name: the value for hydra.job.name (default is \'app\')\n """\n')))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/21854093.45eed3fd.js b/assets/js/21854093.45eed3fd.js deleted file mode 100644 index 8797a3d1cc..0000000000 --- a/assets/js/21854093.45eed3fd.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[6273],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>s,MDXProvider:()=>d,mdx:()=>f,useMDXComponents:()=>p,withMDXComponents:()=>c});var a=n(96540);function l(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function r(){return r=Object.assign||function(e){for(var t=1;t=0||(l[n]=e[n]);return l}(e,t);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(l[n]=e[n])}return l}var s=a.createContext({}),c=function(e){return function(t){var n=p(t.components);return a.createElement(e,r({},t,{components:n}))}},p=function(e){var t=a.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},d=function(e){var t=p(e.components);return a.createElement(s.Provider,{value:t},e.children)},g={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},u=a.forwardRef((function(e,t){var n=e.components,l=e.mdxType,r=e.originalType,o=e.parentName,s=m(e,["components","mdxType","originalType","parentName"]),c=p(n),d=l,u=c["".concat(o,".").concat(d)]||c[d]||g[d]||r;return n?a.createElement(u,i(i({ref:t},s),{},{components:n})):a.createElement(u,i({ref:t},s))}));function f(e,t){var n=arguments,l=t&&t.mdxType;if("string"==typeof e||l){var r=n.length,o=new Array(r);o[0]=u;var i={};for(var m in t)hasOwnProperty.call(t,m)&&(i[m]=t[m]);i.originalType=e,i.mdxType="string"==typeof e?e:l,o[1]=i;for(var s=2;s{n.d(t,{A:()=>m,C:()=>s});var a=n(58168),l=n(96540),r=n(75489),o=n(44586),i=n(74098);function m(e){return l.createElement(r.default,(0,a.A)({},e,{to:(t=e.to,m=(0,i.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==m?void 0:m.name)?n:"current"]+t),target:"_blank"}));var t,n,m}function s(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return l.createElement(m,e,l.createElement("span",null,"\xa0"),l.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},38569:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>s,default:()=>g,frontMatter:()=>m,metadata:()=>c,toc:()=>p});var a=n(58168),l=n(98587),r=(n(96540),n(15680)),o=n(49595),i=["components"],m={id:"select_multiple_configs_from_config_group",title:"Selecting multiple configs from a Config Group"},s=void 0,c={unversionedId:"patterns/select_multiple_configs_from_config_group",id:"patterns/select_multiple_configs_from_config_group",title:"Selecting multiple configs from a Config Group",description:"Problem",source:"@site/docs/patterns/select_multiple_configs_from_config_group.md",sourceDirName:"patterns",slug:"/patterns/select_multiple_configs_from_config_group",permalink:"/docs/patterns/select_multiple_configs_from_config_group",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/patterns/select_multiple_configs_from_config_group.md",tags:[],version:"current",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"select_multiple_configs_from_config_group",title:"Selecting multiple configs from a Config Group"},sidebar:"docs",previous:{title:"Configuring Plugins",permalink:"/docs/patterns/configuring_plugins"},next:{title:"Specializing configuration",permalink:"/docs/patterns/specializing_config"}},p=[{value:"Problem",id:"problem",children:[],level:3},{value:"Solution",id:"solution",children:[],level:3},{value:"Example",id:"example",children:[],level:3},{value:"Overriding packages",id:"overriding-packages",children:[],level:3},{value:"Implementation considerations",id:"implementation-considerations",children:[],level:3}],d={toc:p};function g(e){var t=e.components,n=(0,l.A)(e,i);return(0,r.mdx)("wrapper",(0,a.A)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,r.mdx)(o.C,{text:"Example application",to:"examples/patterns/multi-select",mdxType:"ExampleGithubLink"}),(0,r.mdx)("h3",{id:"problem"},"Problem"),(0,r.mdx)("p",null,"In some scenarios, one may need to select multiple configs from the same Config Group."),(0,r.mdx)("h3",{id:"solution"},"Solution"),(0,r.mdx)("p",null,"Use a list of config names as the value of the config group in the Defaults List or in the command line."),(0,r.mdx)("h3",{id:"example"},"Example"),(0,r.mdx)("p",null,"In this example, we configure a server. The server can host multiple websites at the same time."),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Config directory"',title:'"Config','directory"':!0},"\u251c\u2500\u2500 config.yaml\n\u2514\u2500\u2500 server\n \u251c\u2500\u2500 apache.yaml\n \u2514\u2500\u2500 site\n \u251c\u2500\u2500 amazon.yaml\n \u251c\u2500\u2500 fb.yaml\n \u2514\u2500\u2500 google.yaml\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - server/apache\n\n\n\n\n\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/apache.yaml" {3,4}',title:'"server/apache.yaml"',"{3,4}":!0},"defaults:\n - site:\n - fb\n - google\n\nhost: localhost\nport: 443\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/site/amazon.yaml"',title:'"server/site/amazon.yaml"'},"amazon:\n domain: amazon.com\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/site/fb.yaml"',title:'"server/site/fb.yaml"'},"fb:\n domain: facebook.com\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/site/google.yaml"',title:'"server/site/google.yaml"'},"google:\n domain: google.com\n")))),(0,r.mdx)("p",null,"Output:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py" {3,5}',title:'"$',python:!0,'my_app.py"':!0,"{3,5}":!0},"server:\n site:\n fb:\n domain: facebook.com\n google:\n domain: google.com\n host: localhost\n port: 443\n")),(0,r.mdx)("p",null,"Override the selected sites from the command line by passing a list. e.g:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"title=\"$ python my_app.py 'server/site=[google,amazon]'\" {3,5}",title:'"$',python:!0,"my_app.py":!0,"'server/site":"[google,amazon]'\"","{3,5}":!0},"server:\n site:\n google:\n domain: google.com\n amazon:\n domain: amazon.com\n host: localhost\n port: 443\n")),(0,r.mdx)("h3",{id:"overriding-packages"},"Overriding packages"),(0,r.mdx)("p",null,"You can relocate the package of all the configs in the list. e.g:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/apache.yaml" {2}',title:'"server/apache.yaml"',"{2}":!0},"defaults:\n - site@https:\n - fb\n - google\n\n\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py" {2}',title:'"$',python:!0,'my_app.py"':!0,"{2}":!0},"server:\n https:\n fb:\n domain: facebook.com\n google:\n domain: google.com\n")))),(0,r.mdx)("p",null,"When overriding the selected configs of config groups with overridden packages you need to use the package. e.g:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py server/site@server.https=amazon"',title:'"$',python:!0,"my_app.py":!0,"server/site@server.https":'amazon"'},"server:\n https:\n amazon:\n domain: amazon.com\n host: localhost\n port: 443\n")),(0,r.mdx)("h3",{id:"implementation-considerations"},"Implementation considerations"),(0,r.mdx)("p",null,"A nested list in the Defaults List is interpreted as a list of non-overridable configs:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/apache.yaml" {3,4}',title:'"server/apache.yaml"',"{3,4}":!0},"defaults:\n - site:\n - fb\n - google\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Equivalent to" {2,3}',title:'"Equivalent','to"':!0,"{2,3}":!0},"defaults:\n - site/fb\n - site/google\n\n")))),(0,r.mdx)("p",null,"All default package for all the configs in ",(0,r.mdx)("inlineCode",{parentName:"p"},"server/site")," is ",(0,r.mdx)("inlineCode",{parentName:"p"},"server.site"),".\nThis example uses an explicit nesting level inside each of the website configs to prevent them stepping over one another:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/site/amazon.yaml" {1}',title:'"server/site/amazon.yaml"',"{1}":!0},"amazon:\n ...\n")))}g.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/21854093.c2e54e49.js b/assets/js/21854093.c2e54e49.js new file mode 100644 index 0000000000..13c6aabc5b --- /dev/null +++ b/assets/js/21854093.c2e54e49.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[6273],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>s,MDXProvider:()=>d,mdx:()=>f,useMDXComponents:()=>p,withMDXComponents:()=>c});var a=n(96540);function l(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function r(){return r=Object.assign||function(e){for(var t=1;t=0||(l[n]=e[n]);return l}(e,t);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(l[n]=e[n])}return l}var s=a.createContext({}),c=function(e){return function(t){var n=p(t.components);return a.createElement(e,r({},t,{components:n}))}},p=function(e){var t=a.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},d=function(e){var t=p(e.components);return a.createElement(s.Provider,{value:t},e.children)},g={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},u=a.forwardRef((function(e,t){var n=e.components,l=e.mdxType,r=e.originalType,o=e.parentName,s=m(e,["components","mdxType","originalType","parentName"]),c=p(n),d=l,u=c["".concat(o,".").concat(d)]||c[d]||g[d]||r;return n?a.createElement(u,i(i({ref:t},s),{},{components:n})):a.createElement(u,i({ref:t},s))}));function f(e,t){var n=arguments,l=t&&t.mdxType;if("string"==typeof e||l){var r=n.length,o=new Array(r);o[0]=u;var i={};for(var m in t)hasOwnProperty.call(t,m)&&(i[m]=t[m]);i.originalType=e,i.mdxType="string"==typeof e?e:l,o[1]=i;for(var s=2;s{n.d(t,{A:()=>m,C:()=>s});var a=n(58168),l=n(96540),r=n(75489),o=n(44586),i=n(74098);function m(e){return l.createElement(r.default,(0,a.A)({},e,{to:(t=e.to,m=(0,i.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==m?void 0:m.name)?n:"current"]+t),target:"_blank"}));var t,n,m}function s(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return l.createElement(m,e,l.createElement("span",null,"\xa0"),l.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},38569:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>s,default:()=>g,frontMatter:()=>m,metadata:()=>c,toc:()=>p});var a=n(58168),l=n(98587),r=(n(96540),n(15680)),o=n(49595),i=["components"],m={id:"select_multiple_configs_from_config_group",title:"Selecting multiple configs from a Config Group"},s=void 0,c={unversionedId:"patterns/select_multiple_configs_from_config_group",id:"patterns/select_multiple_configs_from_config_group",title:"Selecting multiple configs from a Config Group",description:"Problem",source:"@site/docs/patterns/select_multiple_configs_from_config_group.md",sourceDirName:"patterns",slug:"/patterns/select_multiple_configs_from_config_group",permalink:"/docs/patterns/select_multiple_configs_from_config_group",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/patterns/select_multiple_configs_from_config_group.md",tags:[],version:"current",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"select_multiple_configs_from_config_group",title:"Selecting multiple configs from a Config Group"},sidebar:"docs",previous:{title:"Configuring Plugins",permalink:"/docs/patterns/configuring_plugins"},next:{title:"Specializing configuration",permalink:"/docs/patterns/specializing_config"}},p=[{value:"Problem",id:"problem",children:[],level:3},{value:"Solution",id:"solution",children:[],level:3},{value:"Example",id:"example",children:[],level:3},{value:"Overriding packages",id:"overriding-packages",children:[],level:3},{value:"Implementation considerations",id:"implementation-considerations",children:[],level:3}],d={toc:p};function g(e){var t=e.components,n=(0,l.A)(e,i);return(0,r.mdx)("wrapper",(0,a.A)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,r.mdx)(o.C,{text:"Example application",to:"examples/patterns/multi-select",mdxType:"ExampleGithubLink"}),(0,r.mdx)("h3",{id:"problem"},"Problem"),(0,r.mdx)("p",null,"In some scenarios, one may need to select multiple configs from the same Config Group."),(0,r.mdx)("h3",{id:"solution"},"Solution"),(0,r.mdx)("p",null,"Use a list of config names as the value of the config group in the Defaults List or in the command line."),(0,r.mdx)("h3",{id:"example"},"Example"),(0,r.mdx)("p",null,"In this example, we configure a server. The server can host multiple websites at the same time."),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Config directory"',title:'"Config','directory"':!0},"\u251c\u2500\u2500 config.yaml\n\u2514\u2500\u2500 server\n \u251c\u2500\u2500 apache.yaml\n \u2514\u2500\u2500 site\n \u251c\u2500\u2500 amazon.yaml\n \u251c\u2500\u2500 fb.yaml\n \u2514\u2500\u2500 google.yaml\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - server/apache\n\n\n\n\n\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/apache.yaml" {3,4}',title:'"server/apache.yaml"',"{3,4}":!0},"defaults:\n - site:\n - fb\n - google\n\nhost: localhost\nport: 443\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/site/amazon.yaml"',title:'"server/site/amazon.yaml"'},"amazon:\n domain: amazon.com\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/site/fb.yaml"',title:'"server/site/fb.yaml"'},"fb:\n domain: facebook.com\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/site/google.yaml"',title:'"server/site/google.yaml"'},"google:\n domain: google.com\n")))),(0,r.mdx)("p",null,"Output:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py" {3,5}',title:'"$',python:!0,'my_app.py"':!0,"{3,5}":!0},"server:\n site:\n fb:\n domain: facebook.com\n google:\n domain: google.com\n host: localhost\n port: 443\n")),(0,r.mdx)("p",null,"Override the selected sites from the command line by passing a list. e.g:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"title=\"$ python my_app.py 'server/site=[google,amazon]'\" {3,5}",title:'"$',python:!0,"my_app.py":!0,"'server/site":"[google,amazon]'\"","{3,5}":!0},"server:\n site:\n google:\n domain: google.com\n amazon:\n domain: amazon.com\n host: localhost\n port: 443\n")),(0,r.mdx)("h3",{id:"overriding-packages"},"Overriding packages"),(0,r.mdx)("p",null,"You can relocate the package of all the configs in the list. e.g:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/apache.yaml" {2}',title:'"server/apache.yaml"',"{2}":!0},"defaults:\n - site@https:\n - fb\n - google\n\n\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py" {2}',title:'"$',python:!0,'my_app.py"':!0,"{2}":!0},"server:\n https:\n fb:\n domain: facebook.com\n google:\n domain: google.com\n")))),(0,r.mdx)("p",null,"When overriding the selected configs of config groups with overridden packages you need to use the package. e.g:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py server/site@server.https=amazon"',title:'"$',python:!0,"my_app.py":!0,"server/site@server.https":'amazon"'},"server:\n https:\n amazon:\n domain: amazon.com\n host: localhost\n port: 443\n")),(0,r.mdx)("h3",{id:"implementation-considerations"},"Implementation considerations"),(0,r.mdx)("p",null,"A nested list in the Defaults List is interpreted as a list of non-overridable configs:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/apache.yaml" {3,4}',title:'"server/apache.yaml"',"{3,4}":!0},"defaults:\n - site:\n - fb\n - google\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Equivalent to" {2,3}',title:'"Equivalent','to"':!0,"{2,3}":!0},"defaults:\n - site/fb\n - site/google\n\n")))),(0,r.mdx)("p",null,"All default package for all the configs in ",(0,r.mdx)("inlineCode",{parentName:"p"},"server/site")," is ",(0,r.mdx)("inlineCode",{parentName:"p"},"server.site"),".\nThis example uses an explicit nesting level inside each of the website configs to prevent them stepping over one another:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/site/amazon.yaml" {1}',title:'"server/site/amazon.yaml"',"{1}":!0},"amazon:\n ...\n")))}g.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/21edddaf.653828a2.js b/assets/js/21edddaf.653828a2.js deleted file mode 100644 index da83af5ca0..0000000000 --- a/assets/js/21edddaf.653828a2.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[6578],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>o,MDXProvider:()=>u,mdx:()=>x,useMDXComponents:()=>p,withMDXComponents:()=>s});var a=t(96540);function r(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function l(){return l=Object.assign||function(e){for(var n=1;n=0||(r[t]=e[t]);return r}(e,n);if(Object.getOwnPropertySymbols){var l=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(r[t]=e[t])}return r}var o=a.createContext({}),s=function(e){return function(n){var t=p(n.components);return a.createElement(e,l({},n,{components:t}))}},p=function(e){var n=a.useContext(o),t=n;return e&&(t="function"==typeof e?e(n):i(i({},n),e)),t},u=function(e){var n=p(e.components);return a.createElement(o.Provider,{value:n},e.children)},g={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},c=a.forwardRef((function(e,n){var t=e.components,r=e.mdxType,l=e.originalType,d=e.parentName,o=m(e,["components","mdxType","originalType","parentName"]),s=p(t),u=r,c=s["".concat(d,".").concat(u)]||s[u]||g[u]||l;return t?a.createElement(c,i(i({ref:n},o),{},{components:t})):a.createElement(c,i({ref:n},o))}));function x(e,n){var t=arguments,r=n&&n.mdxType;if("string"==typeof e||r){var l=t.length,d=new Array(l);d[0]=c;var i={};for(var m in n)hasOwnProperty.call(n,m)&&(i[m]=n[m]);i.originalType=e,i.mdxType="string"==typeof e?e:r,d[1]=i;for(var o=2;o{t.r(n),t.d(n,{contentTitle:()=>m,default:()=>u,frontMatter:()=>i,metadata:()=>o,toc:()=>s});var a=t(58168),r=t(98587),l=(t(96540),t(15680)),d=["components"],i={id:"extended",sidebar_label:"Extended Override syntax",hide_title:!0},m=void 0,o={unversionedId:"advanced/override_grammar/extended",id:"version-1.0/advanced/override_grammar/extended",title:"extended",description:"Extended Override syntax",source:"@site/versioned_docs/version-1.0/advanced/override_grammar/extended.md",sourceDirName:"advanced/override_grammar",slug:"/advanced/override_grammar/extended",permalink:"/docs/1.0/advanced/override_grammar/extended",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.0/advanced/override_grammar/extended.md",tags:[],version:"1.0",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"extended",sidebar_label:"Extended Override syntax",hide_title:!0},sidebar:"version-1.0/docs",previous:{title:"Basic Override syntax",permalink:"/docs/1.0/advanced/override_grammar/basic"},next:{title:"Overriding packages",permalink:"/docs/1.0/advanced/overriding_packages"}},s=[{value:"Extended Override syntax",id:"extended-override-syntax",children:[],level:2},{value:"Sweeps",id:"sweeps",children:[{value:"Choice sweep",id:"choice-sweep",children:[],level:3},{value:"Glob choice sweep",id:"glob-choice-sweep",children:[],level:3},{value:"Range sweep",id:"range-sweep",children:[],level:3},{value:"Interval sweep",id:"interval-sweep",children:[],level:3},{value:"Tag",id:"tag",children:[],level:3}],level:2},{value:"Reordering lists and sweeps",id:"reordering-lists-and-sweeps",children:[{value:"sort",id:"sort",children:[],level:3},{value:"shuffle",id:"shuffle",children:[],level:3}],level:2},{value:"Type casting",id:"type-casting",children:[{value:"Casting string to bool",id:"casting-string-to-bool",children:[],level:4},{value:"Casting lists",id:"casting-lists",children:[],level:4},{value:"Casting dicts",id:"casting-dicts",children:[],level:4},{value:"Casting ranges",id:"casting-ranges",children:[],level:4},{value:"Conversion matrix",id:"conversion-matrix",children:[],level:3}],level:2}],p={toc:s};function u(e){var n=e.components,t=(0,r.A)(e,d);return(0,l.mdx)("wrapper",(0,a.A)({},p,t,{components:n,mdxType:"MDXLayout"}),(0,l.mdx)("h2",{id:"extended-override-syntax"},"Extended Override syntax"),(0,l.mdx)("p",null,"Hydra Overrides supports functions.\nWhen calling a function, one can optionally name parameters. This is following the Python\nconvention of naming parameters."),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Example function"',title:'"Example','function"':!0},"def func(a:int, b:str) -> bool:\n ...\n\n\n"))),(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Calling function"',title:'"Calling','function"':!0},"func(10,foo) # Positional only\nfunc(a=10,b=foo) # Named only\nfunc(10,b=foo) # Mixed\nfunc(a=10,foo) # Error\n")))),(0,l.mdx)("p",null,"Note the lack of quotes in the examples above. Despite some similarities, this is ",(0,l.mdx)("strong",{parentName:"p"},"not Python"),"."),(0,l.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,l.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,l.mdx)("h5",{parentName:"div"},(0,l.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,l.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,l.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,l.mdx)("div",{parentName:"div",className:"admonition-content"},(0,l.mdx)("p",{parentName:"div"},"Hydra supports very specific functions. If you would like to have\nanother function added, please file an issue and explain the use case."))),(0,l.mdx)("h2",{id:"sweeps"},"Sweeps"),(0,l.mdx)("p",null,"Sweep overrides are used by Sweepers to determine what to do. For example,\none can instruct the Basic Sweeper to sweep over all combinations of the\nranges ",(0,l.mdx)("inlineCode",{parentName:"p"},"num1=range(0,3)")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"num2=range(0,3)")," - resulting in ",(0,l.mdx)("inlineCode",{parentName:"p"},"9")," jobs, each getting a\ndifferent pair of numbers from ",(0,l.mdx)("inlineCode",{parentName:"p"},"0"),", ",(0,l.mdx)("inlineCode",{parentName:"p"},"1")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"2"),"."),(0,l.mdx)("h3",{id:"choice-sweep"},"Choice sweep"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def choice(\n *args: Union[str, int, float, bool, Dict[Any, Any], List[Any], ChoiceSweep]\n) -> ChoiceSweep:\n """\n A choice sweep over the specified values\n """\n')),(0,l.mdx)("p",null,"Choice sweeps are the most common sweeps.\nA choice sweep is described in one of two equivalent forms."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"db=mysql,postgresql # a comma separated list of two or more elements. \ndb=choice(mysql,postgresql) # choice\n")),(0,l.mdx)("h3",{id:"glob-choice-sweep"},"Glob choice sweep"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def glob(\n include: Union[List[str], str], exclude: Optional[Union[List[str], str]] = None\n) -> Glob:\n """\n A glob selects from all options in the config group.\n inputs are in glob format. e.g: *, foo*, *foo.\n :param include: a string or a list of strings to use as include globs\n :param exclude: a string or a list of strings to use as exclude globs\n :return: A Glob object\n """\n')),(0,l.mdx)("p",null,"Assuming the config group ",(0,l.mdx)("strong",{parentName:"p"},"schema")," with the options ",(0,l.mdx)("strong",{parentName:"p"},"school"),", ",(0,l.mdx)("strong",{parentName:"p"},"support")," and ",(0,l.mdx)("strong",{parentName:"p"},"warehouse"),":"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"schema=glob(*) # school,support,warehouse\nschema=glob(*,exclude=support) # school,warehouse\nschema=glob([s*,w*],exclude=school) # support,warehouse\n")),(0,l.mdx)("h3",{id:"range-sweep"},"Range sweep"),(0,l.mdx)("p",null,"Unlike Python, Hydra's range can be used with both integer and floating-point numbers.\nIn both cases, the range represents a discrete list of values."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def range(\n start: Union[int, float], stop: Union[int, float], step: Union[int, float] = 1\n) -> RangeSweep:\n """\n Range is defines a sweeep over a range of integer or floating-point values.\n For a positive step, the contents of a range r are determined by the formula\n r[i] = start + step*i where i >= 0 and r[i] < stop.\n For a negative step, the contents of the range are still determined by the formula\n r[i] = start + step*i, but the constraints are i >= 0 and r[i] > stop.\n """\n')),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"num=range(0,5) # 0,1,2,3,4\nnum=range(0,5,2) # 0,2,4\nnum=range(0,10,3.3) # 0.0,3.3,6.6,9.9\n")),(0,l.mdx)("h3",{id:"interval-sweep"},"Interval sweep"),(0,l.mdx)("p",null,"An interval sweep represents all the floating point value between two values.\nThis is used by optimizing sweepers like Ax and Nevergrad. The basic sweeper does not support interval."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def interval(start: Union[int, float], end: Union[int, float]) -> IntervalSweep:\n """\n A continuous interval between two floating point values.\n value=interval(x,y) is interpreted as x <= value < y\n """\n')),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"interval(1.0,5.0) # 1.0 <= x < 5.0\ninterval(1,5) # 1.0 <= x < 5.0, auto-cast to floats\n")),(0,l.mdx)("h3",{id:"tag"},"Tag"),(0,l.mdx)("p",null,"With tags you can add arbitrary metadata to a sweep. The metadata can be used by advanced sweepers."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def tag(*args: Union[str, Union[Sweep]], sweep: Optional[Sweep] = None) -> Sweep:\n """\n Tags the sweep with a list of string tags.\n """\n')),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"tag(log,interval(0,1)) # 1.0 <= x < 1.0, tags=[log]\ntag(foo,bar,interval(0,1)) # 1.0 <= x < 1.0, tags=[foo,bar]\n")),(0,l.mdx)("h2",{id:"reordering-lists-and-sweeps"},"Reordering lists and sweeps"),(0,l.mdx)("h3",{id:"sort"},"sort"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def sort(\n *args: Union[ElementType, ChoiceSweep, RangeSweep],\n sweep: Optional[Union[ChoiceSweep, RangeSweep]] = None,\n list: Optional[List[Any]] = None,\n reverse: bool = False,\n) -> Any:\n """\n Sort an input list or sweep.\n reverse=True reverses the order\n """\n')),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"# sweep\nsort(1,3,2) # ChoiceSweep(1,2,3)\nsort(1,3,2,reverse=true) # ChoiceSweep(3,2,1)\nsort(choice(1,2,3)) # ChoiceSweep(1,2,3)\nsort(sweep=choice(1,2,3)) # ChoiceSweep(1,2,3)\nsort(choice(1,2,3),reverse=true) # ChoiceSweep(3,2,1)\nsort(range(10,1)) # range in ascending order\nsort(range(1,10),reverse=true) # range in descending order\n\n# lists\nsort([1,3,2]) # [1,2,3]\nsort(list=[1,3,2]) # [1,2,3]\nsort(list=[1,3,2], reverse=true) # [3,2,1]\n\n# single value returned as is\nsort(1) # 1\n")),(0,l.mdx)("h3",{id:"shuffle"},"shuffle"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def shuffle(\n *args: Union[ElementType, ChoiceSweep, RangeSweep],\n sweep: Optional[Union[ChoiceSweep, RangeSweep]] = None,\n list: Optional[List[Any]] = None,\n) -> Union[List[Any], ChoiceSweep, RangeSweep]:\n """\n Shuffle input list or sweep (does not support interval)\n """\n')),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"shuffle(a,b,c) # shuffled a,b,c\nshuffle(choice(a,b,c)), shuffle(sweep=choice(a,b,c)) # shuffled choice(a,b,c)\nshuffle(range(1,10)) # shuffled range(1,10)\nshuffle([a,b,c]), shuffle(list=[a,b,c]) # shuffled list [a,b,c] \n")),(0,l.mdx)("h2",{id:"type-casting"},"Type casting"),(0,l.mdx)("p",null,"You can cast values and sweeps to ",(0,l.mdx)("inlineCode",{parentName:"p"},"int"),", ",(0,l.mdx)("inlineCode",{parentName:"p"},"float"),", ",(0,l.mdx)("inlineCode",{parentName:"p"},"bool")," or ",(0,l.mdx)("inlineCode",{parentName:"p"},"str"),"."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Example"',title:'"Example"'},"int(3.14) # 3 (int)\nint(value=3.14) # 3 (int)\nfloat(10) # 10.0 (float)\nstr(10) # \"10\" (str)\nbool(1) # true (bool)\nfloat(range(1,10)) # range(1.0,10.0)\nstr([1,2,3]) # ['1','2','3']\nstr({a:10}) # {a:'10'}\n")),(0,l.mdx)("p",null,"Below are pseudo code snippets that illustrates the differences between Python's casting and Hydra's casting."),(0,l.mdx)("h4",{id:"casting-string-to-bool"},"Casting string to bool"),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Python"',title:'"Python"'},"def bool(value: Any) -> bool:\n if isinstance(value, str):\n return len(value) > 0\n else:\n return bool(value)\n\n\n\n\n"))),(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Hydra"',title:'"Hydra"'},'def bool(s: str) -> bool:\n if isinstance(value, str):\n if value.lower() == "false":\n return False\n elif value.lower() == "true":\n return True\n else:\n raise ValueError()\n return bool(value)\n')))),(0,l.mdx)("h4",{id:"casting-lists"},"Casting lists"),(0,l.mdx)("p",null,"Casting lists results in a list where each element is recursively cast.\nFailure to cast an element in the list fails the cast of the list."),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Python"',title:'"Python"'},"def cast_int(value: Any):\n if isinstance(value, list):\n raise TypeError()\n else:\n return int(v)\n\n\n"))),(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Hydra"',title:'"Hydra"'},"def cast_int(value: Any):\n if isinstance(v, list):\n return list(map(cast_int, v))\n else:\n return int(v)\n\n\n")))),(0,l.mdx)("h4",{id:"casting-dicts"},"Casting dicts"),(0,l.mdx)("p",null,"Casting dicts results in a dict where values are recursively cast, but keys are unchanged.\nFailure to cast a value in the dict fails the cast of the entire dict."),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Python"',title:'"Python"'},"def cast_int(value: Any):\n if isinstance(value, dict):\n raise TypeError()\n else:\n return int(v)\n\n\n"))),(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Hydra"',title:'"Hydra"'},"def cast_int(value: Any):\n if isinstance(value, dict):\n return apply_to_values(\n value, cast_int\n )\n else:\n return int(v)\n")))),(0,l.mdx)("h4",{id:"casting-ranges"},"Casting ranges"),(0,l.mdx)("p",null,"Ranges can be cast to float or int, resulting in start, stop and step being cast and thus the range elements being cast."),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Python"',title:'"Python"'},"def cast_int(value: Any):\n if isinstance(value, RangeSweep):\n raise TypeError()\n else:\n return int(v)\n\n\n\n\n"))),(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Hydra"',title:'"Hydra"'},"def cast_int(value: Any):\n if isinstance(value, RangeSweep):\n return RangeSweep(\n start=cast_int(value.start),\n stop=cast_int(value.stop),\n step=cast_int(value.step),\n )\n else:\n return int(v)\n")))),(0,l.mdx)("h3",{id:"conversion-matrix"},"Conversion matrix"),(0,l.mdx)("p",null,"Below is the conversion matrix from various inputs to all supported types.\nInput are grouped by type."),(0,l.mdx)("table",null,(0,l.mdx)("thead",{parentName:"table"},(0,l.mdx)("tr",{parentName:"thead"},(0,l.mdx)("th",{parentName:"tr",align:null}),(0,l.mdx)("th",{parentName:"tr",align:null},"int()"),(0,l.mdx)("th",{parentName:"tr",align:null},"float()"),(0,l.mdx)("th",{parentName:"tr",align:null},"str()"),(0,l.mdx)("th",{parentName:"tr",align:null},"bool()"))),(0,l.mdx)("tbody",{parentName:"table"},(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"10"),(0,l.mdx)("td",{parentName:"tr",align:null},"10"),(0,l.mdx)("td",{parentName:"tr",align:null},"10.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c10\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"0"),(0,l.mdx)("td",{parentName:"tr",align:null},"0"),(0,l.mdx)("td",{parentName:"tr",align:null},"0.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c0\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"false")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"10.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"10"),(0,l.mdx)("td",{parentName:"tr",align:null},"10.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c10.0\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"0.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"0"),(0,l.mdx)("td",{parentName:"tr",align:null},"0.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c0.0\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"false")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"inf"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"inf"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u2018inf\u2019"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"nan"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"nan"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u2018nan\u2019"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"1e6"),(0,l.mdx)("td",{parentName:"tr",align:null},"1,000,000"),(0,l.mdx)("td",{parentName:"tr",align:null},"1e6"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u20181000000.0\u2019"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"foo"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"foo"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c\u201d (empty string)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c10\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"10"),(0,l.mdx)("td",{parentName:"tr",align:null},"10.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c10\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c10.0\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"10.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c10.0\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201ctrue\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201ctrue\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201cfalse\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201cfalse\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"false")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c","[1,2,3]","\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c","[1,2,3]","\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c{a:10}\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c{a:10}\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"1"),(0,l.mdx)("td",{parentName:"tr",align:null},"1.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201ctrue\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"0"),(0,l.mdx)("td",{parentName:"tr",align:null},"0.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201cfalse\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"false")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"[]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[]")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"[0,1,2]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[0,1,2]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[0.0,1.0,2.0]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[\u201c0\u201d,\u201d1\u201d,\u201d2\u201d]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[false,true,true]")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"[1,","[2]","]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[1,","[2]","]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[1.0,","[2.0]","]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[\u201c1\u201d,","[\u201c2\u201d]","]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[true,","[true]","]")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"[a,1]"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"[\u201ca\u201d,\u201d1\u201d]"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"{}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{}")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"{a:10}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:10}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:10.0}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:\u201d10\u201d}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a: true}")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"{a:","[0,1,2]","}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:","[0,1,2]","}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:","[0.0,1.0,2.-]","}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:","[\u201c0\u201d,\u201d1\u201d,\u201d2\u201d]","}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:","[false,true,true]","}")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"{a:10,b:xyz}"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:\u201d10\u201d,b:\u201dxyz\u201d}"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"choice(0,1)"),(0,l.mdx)("td",{parentName:"tr",align:null},"choice(0,1)"),(0,l.mdx)("td",{parentName:"tr",align:null},"choice(0.0,1.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"choice(\u201c0\u201d,\u201c1\u201d)"),(0,l.mdx)("td",{parentName:"tr",align:null},"choice(false,true)")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"choice(a,b)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"choice(\u201ca\u201d,\u201db\u201d)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"choice(1,a)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"choice(\u201c1\u201d,\u201da\u201d)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"interval(1.0, 2.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"interval(1, 2)"),(0,l.mdx)("td",{parentName:"tr",align:null},"interval(1.0, 2.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"interval(1, 2)"),(0,l.mdx)("td",{parentName:"tr",align:null},"interval(1, 2)"),(0,l.mdx)("td",{parentName:"tr",align:null},"interval(1.0, 2.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"range(1,10)"),(0,l.mdx)("td",{parentName:"tr",align:null},"range(1,10)"),(0,l.mdx)("td",{parentName:"tr",align:null},"range(1.0,10.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"range(1.0, 10.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"range(1,10)"),(0,l.mdx)("td",{parentName:"tr",align:null},"range(1.0,10.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")))))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/21edddaf.e4790538.js b/assets/js/21edddaf.e4790538.js new file mode 100644 index 0000000000..8913c40c79 --- /dev/null +++ b/assets/js/21edddaf.e4790538.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[6578],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>o,MDXProvider:()=>u,mdx:()=>x,useMDXComponents:()=>p,withMDXComponents:()=>s});var a=t(96540);function r(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function l(){return l=Object.assign||function(e){for(var n=1;n=0||(r[t]=e[t]);return r}(e,n);if(Object.getOwnPropertySymbols){var l=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(r[t]=e[t])}return r}var o=a.createContext({}),s=function(e){return function(n){var t=p(n.components);return a.createElement(e,l({},n,{components:t}))}},p=function(e){var n=a.useContext(o),t=n;return e&&(t="function"==typeof e?e(n):i(i({},n),e)),t},u=function(e){var n=p(e.components);return a.createElement(o.Provider,{value:n},e.children)},g={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},c=a.forwardRef((function(e,n){var t=e.components,r=e.mdxType,l=e.originalType,d=e.parentName,o=m(e,["components","mdxType","originalType","parentName"]),s=p(t),u=r,c=s["".concat(d,".").concat(u)]||s[u]||g[u]||l;return t?a.createElement(c,i(i({ref:n},o),{},{components:t})):a.createElement(c,i({ref:n},o))}));function x(e,n){var t=arguments,r=n&&n.mdxType;if("string"==typeof e||r){var l=t.length,d=new Array(l);d[0]=c;var i={};for(var m in n)hasOwnProperty.call(n,m)&&(i[m]=n[m]);i.originalType=e,i.mdxType="string"==typeof e?e:r,d[1]=i;for(var o=2;o{t.r(n),t.d(n,{contentTitle:()=>m,default:()=>u,frontMatter:()=>i,metadata:()=>o,toc:()=>s});var a=t(58168),r=t(98587),l=(t(96540),t(15680)),d=["components"],i={id:"extended",sidebar_label:"Extended Override syntax",hide_title:!0},m=void 0,o={unversionedId:"advanced/override_grammar/extended",id:"version-1.0/advanced/override_grammar/extended",title:"extended",description:"Extended Override syntax",source:"@site/versioned_docs/version-1.0/advanced/override_grammar/extended.md",sourceDirName:"advanced/override_grammar",slug:"/advanced/override_grammar/extended",permalink:"/docs/1.0/advanced/override_grammar/extended",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.0/advanced/override_grammar/extended.md",tags:[],version:"1.0",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"extended",sidebar_label:"Extended Override syntax",hide_title:!0},sidebar:"version-1.0/docs",previous:{title:"Basic Override syntax",permalink:"/docs/1.0/advanced/override_grammar/basic"},next:{title:"Overriding packages",permalink:"/docs/1.0/advanced/overriding_packages"}},s=[{value:"Extended Override syntax",id:"extended-override-syntax",children:[],level:2},{value:"Sweeps",id:"sweeps",children:[{value:"Choice sweep",id:"choice-sweep",children:[],level:3},{value:"Glob choice sweep",id:"glob-choice-sweep",children:[],level:3},{value:"Range sweep",id:"range-sweep",children:[],level:3},{value:"Interval sweep",id:"interval-sweep",children:[],level:3},{value:"Tag",id:"tag",children:[],level:3}],level:2},{value:"Reordering lists and sweeps",id:"reordering-lists-and-sweeps",children:[{value:"sort",id:"sort",children:[],level:3},{value:"shuffle",id:"shuffle",children:[],level:3}],level:2},{value:"Type casting",id:"type-casting",children:[{value:"Casting string to bool",id:"casting-string-to-bool",children:[],level:4},{value:"Casting lists",id:"casting-lists",children:[],level:4},{value:"Casting dicts",id:"casting-dicts",children:[],level:4},{value:"Casting ranges",id:"casting-ranges",children:[],level:4},{value:"Conversion matrix",id:"conversion-matrix",children:[],level:3}],level:2}],p={toc:s};function u(e){var n=e.components,t=(0,r.A)(e,d);return(0,l.mdx)("wrapper",(0,a.A)({},p,t,{components:n,mdxType:"MDXLayout"}),(0,l.mdx)("h2",{id:"extended-override-syntax"},"Extended Override syntax"),(0,l.mdx)("p",null,"Hydra Overrides supports functions.\nWhen calling a function, one can optionally name parameters. This is following the Python\nconvention of naming parameters."),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Example function"',title:'"Example','function"':!0},"def func(a:int, b:str) -> bool:\n ...\n\n\n"))),(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Calling function"',title:'"Calling','function"':!0},"func(10,foo) # Positional only\nfunc(a=10,b=foo) # Named only\nfunc(10,b=foo) # Mixed\nfunc(a=10,foo) # Error\n")))),(0,l.mdx)("p",null,"Note the lack of quotes in the examples above. Despite some similarities, this is ",(0,l.mdx)("strong",{parentName:"p"},"not Python"),"."),(0,l.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,l.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,l.mdx)("h5",{parentName:"div"},(0,l.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,l.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,l.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,l.mdx)("div",{parentName:"div",className:"admonition-content"},(0,l.mdx)("p",{parentName:"div"},"Hydra supports very specific functions. If you would like to have\nanother function added, please file an issue and explain the use case."))),(0,l.mdx)("h2",{id:"sweeps"},"Sweeps"),(0,l.mdx)("p",null,"Sweep overrides are used by Sweepers to determine what to do. For example,\none can instruct the Basic Sweeper to sweep over all combinations of the\nranges ",(0,l.mdx)("inlineCode",{parentName:"p"},"num1=range(0,3)")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"num2=range(0,3)")," - resulting in ",(0,l.mdx)("inlineCode",{parentName:"p"},"9")," jobs, each getting a\ndifferent pair of numbers from ",(0,l.mdx)("inlineCode",{parentName:"p"},"0"),", ",(0,l.mdx)("inlineCode",{parentName:"p"},"1")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"2"),"."),(0,l.mdx)("h3",{id:"choice-sweep"},"Choice sweep"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def choice(\n *args: Union[str, int, float, bool, Dict[Any, Any], List[Any], ChoiceSweep]\n) -> ChoiceSweep:\n """\n A choice sweep over the specified values\n """\n')),(0,l.mdx)("p",null,"Choice sweeps are the most common sweeps.\nA choice sweep is described in one of two equivalent forms."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"db=mysql,postgresql # a comma separated list of two or more elements. \ndb=choice(mysql,postgresql) # choice\n")),(0,l.mdx)("h3",{id:"glob-choice-sweep"},"Glob choice sweep"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def glob(\n include: Union[List[str], str], exclude: Optional[Union[List[str], str]] = None\n) -> Glob:\n """\n A glob selects from all options in the config group.\n inputs are in glob format. e.g: *, foo*, *foo.\n :param include: a string or a list of strings to use as include globs\n :param exclude: a string or a list of strings to use as exclude globs\n :return: A Glob object\n """\n')),(0,l.mdx)("p",null,"Assuming the config group ",(0,l.mdx)("strong",{parentName:"p"},"schema")," with the options ",(0,l.mdx)("strong",{parentName:"p"},"school"),", ",(0,l.mdx)("strong",{parentName:"p"},"support")," and ",(0,l.mdx)("strong",{parentName:"p"},"warehouse"),":"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"schema=glob(*) # school,support,warehouse\nschema=glob(*,exclude=support) # school,warehouse\nschema=glob([s*,w*],exclude=school) # support,warehouse\n")),(0,l.mdx)("h3",{id:"range-sweep"},"Range sweep"),(0,l.mdx)("p",null,"Unlike Python, Hydra's range can be used with both integer and floating-point numbers.\nIn both cases, the range represents a discrete list of values."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def range(\n start: Union[int, float], stop: Union[int, float], step: Union[int, float] = 1\n) -> RangeSweep:\n """\n Range is defines a sweeep over a range of integer or floating-point values.\n For a positive step, the contents of a range r are determined by the formula\n r[i] = start + step*i where i >= 0 and r[i] < stop.\n For a negative step, the contents of the range are still determined by the formula\n r[i] = start + step*i, but the constraints are i >= 0 and r[i] > stop.\n """\n')),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"num=range(0,5) # 0,1,2,3,4\nnum=range(0,5,2) # 0,2,4\nnum=range(0,10,3.3) # 0.0,3.3,6.6,9.9\n")),(0,l.mdx)("h3",{id:"interval-sweep"},"Interval sweep"),(0,l.mdx)("p",null,"An interval sweep represents all the floating point value between two values.\nThis is used by optimizing sweepers like Ax and Nevergrad. The basic sweeper does not support interval."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def interval(start: Union[int, float], end: Union[int, float]) -> IntervalSweep:\n """\n A continuous interval between two floating point values.\n value=interval(x,y) is interpreted as x <= value < y\n """\n')),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"interval(1.0,5.0) # 1.0 <= x < 5.0\ninterval(1,5) # 1.0 <= x < 5.0, auto-cast to floats\n")),(0,l.mdx)("h3",{id:"tag"},"Tag"),(0,l.mdx)("p",null,"With tags you can add arbitrary metadata to a sweep. The metadata can be used by advanced sweepers."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def tag(*args: Union[str, Union[Sweep]], sweep: Optional[Sweep] = None) -> Sweep:\n """\n Tags the sweep with a list of string tags.\n """\n')),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"tag(log,interval(0,1)) # 1.0 <= x < 1.0, tags=[log]\ntag(foo,bar,interval(0,1)) # 1.0 <= x < 1.0, tags=[foo,bar]\n")),(0,l.mdx)("h2",{id:"reordering-lists-and-sweeps"},"Reordering lists and sweeps"),(0,l.mdx)("h3",{id:"sort"},"sort"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def sort(\n *args: Union[ElementType, ChoiceSweep, RangeSweep],\n sweep: Optional[Union[ChoiceSweep, RangeSweep]] = None,\n list: Optional[List[Any]] = None,\n reverse: bool = False,\n) -> Any:\n """\n Sort an input list or sweep.\n reverse=True reverses the order\n """\n')),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"# sweep\nsort(1,3,2) # ChoiceSweep(1,2,3)\nsort(1,3,2,reverse=true) # ChoiceSweep(3,2,1)\nsort(choice(1,2,3)) # ChoiceSweep(1,2,3)\nsort(sweep=choice(1,2,3)) # ChoiceSweep(1,2,3)\nsort(choice(1,2,3),reverse=true) # ChoiceSweep(3,2,1)\nsort(range(10,1)) # range in ascending order\nsort(range(1,10),reverse=true) # range in descending order\n\n# lists\nsort([1,3,2]) # [1,2,3]\nsort(list=[1,3,2]) # [1,2,3]\nsort(list=[1,3,2], reverse=true) # [3,2,1]\n\n# single value returned as is\nsort(1) # 1\n")),(0,l.mdx)("h3",{id:"shuffle"},"shuffle"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def shuffle(\n *args: Union[ElementType, ChoiceSweep, RangeSweep],\n sweep: Optional[Union[ChoiceSweep, RangeSweep]] = None,\n list: Optional[List[Any]] = None,\n) -> Union[List[Any], ChoiceSweep, RangeSweep]:\n """\n Shuffle input list or sweep (does not support interval)\n """\n')),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"shuffle(a,b,c) # shuffled a,b,c\nshuffle(choice(a,b,c)), shuffle(sweep=choice(a,b,c)) # shuffled choice(a,b,c)\nshuffle(range(1,10)) # shuffled range(1,10)\nshuffle([a,b,c]), shuffle(list=[a,b,c]) # shuffled list [a,b,c] \n")),(0,l.mdx)("h2",{id:"type-casting"},"Type casting"),(0,l.mdx)("p",null,"You can cast values and sweeps to ",(0,l.mdx)("inlineCode",{parentName:"p"},"int"),", ",(0,l.mdx)("inlineCode",{parentName:"p"},"float"),", ",(0,l.mdx)("inlineCode",{parentName:"p"},"bool")," or ",(0,l.mdx)("inlineCode",{parentName:"p"},"str"),"."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Example"',title:'"Example"'},"int(3.14) # 3 (int)\nint(value=3.14) # 3 (int)\nfloat(10) # 10.0 (float)\nstr(10) # \"10\" (str)\nbool(1) # true (bool)\nfloat(range(1,10)) # range(1.0,10.0)\nstr([1,2,3]) # ['1','2','3']\nstr({a:10}) # {a:'10'}\n")),(0,l.mdx)("p",null,"Below are pseudo code snippets that illustrates the differences between Python's casting and Hydra's casting."),(0,l.mdx)("h4",{id:"casting-string-to-bool"},"Casting string to bool"),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Python"',title:'"Python"'},"def bool(value: Any) -> bool:\n if isinstance(value, str):\n return len(value) > 0\n else:\n return bool(value)\n\n\n\n\n"))),(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Hydra"',title:'"Hydra"'},'def bool(s: str) -> bool:\n if isinstance(value, str):\n if value.lower() == "false":\n return False\n elif value.lower() == "true":\n return True\n else:\n raise ValueError()\n return bool(value)\n')))),(0,l.mdx)("h4",{id:"casting-lists"},"Casting lists"),(0,l.mdx)("p",null,"Casting lists results in a list where each element is recursively cast.\nFailure to cast an element in the list fails the cast of the list."),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Python"',title:'"Python"'},"def cast_int(value: Any):\n if isinstance(value, list):\n raise TypeError()\n else:\n return int(v)\n\n\n"))),(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Hydra"',title:'"Hydra"'},"def cast_int(value: Any):\n if isinstance(v, list):\n return list(map(cast_int, v))\n else:\n return int(v)\n\n\n")))),(0,l.mdx)("h4",{id:"casting-dicts"},"Casting dicts"),(0,l.mdx)("p",null,"Casting dicts results in a dict where values are recursively cast, but keys are unchanged.\nFailure to cast a value in the dict fails the cast of the entire dict."),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Python"',title:'"Python"'},"def cast_int(value: Any):\n if isinstance(value, dict):\n raise TypeError()\n else:\n return int(v)\n\n\n"))),(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Hydra"',title:'"Hydra"'},"def cast_int(value: Any):\n if isinstance(value, dict):\n return apply_to_values(\n value, cast_int\n )\n else:\n return int(v)\n")))),(0,l.mdx)("h4",{id:"casting-ranges"},"Casting ranges"),(0,l.mdx)("p",null,"Ranges can be cast to float or int, resulting in start, stop and step being cast and thus the range elements being cast."),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Python"',title:'"Python"'},"def cast_int(value: Any):\n if isinstance(value, RangeSweep):\n raise TypeError()\n else:\n return int(v)\n\n\n\n\n"))),(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Hydra"',title:'"Hydra"'},"def cast_int(value: Any):\n if isinstance(value, RangeSweep):\n return RangeSweep(\n start=cast_int(value.start),\n stop=cast_int(value.stop),\n step=cast_int(value.step),\n )\n else:\n return int(v)\n")))),(0,l.mdx)("h3",{id:"conversion-matrix"},"Conversion matrix"),(0,l.mdx)("p",null,"Below is the conversion matrix from various inputs to all supported types.\nInput are grouped by type."),(0,l.mdx)("table",null,(0,l.mdx)("thead",{parentName:"table"},(0,l.mdx)("tr",{parentName:"thead"},(0,l.mdx)("th",{parentName:"tr",align:null}),(0,l.mdx)("th",{parentName:"tr",align:null},"int()"),(0,l.mdx)("th",{parentName:"tr",align:null},"float()"),(0,l.mdx)("th",{parentName:"tr",align:null},"str()"),(0,l.mdx)("th",{parentName:"tr",align:null},"bool()"))),(0,l.mdx)("tbody",{parentName:"table"},(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"10"),(0,l.mdx)("td",{parentName:"tr",align:null},"10"),(0,l.mdx)("td",{parentName:"tr",align:null},"10.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c10\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"0"),(0,l.mdx)("td",{parentName:"tr",align:null},"0"),(0,l.mdx)("td",{parentName:"tr",align:null},"0.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c0\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"false")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"10.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"10"),(0,l.mdx)("td",{parentName:"tr",align:null},"10.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c10.0\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"0.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"0"),(0,l.mdx)("td",{parentName:"tr",align:null},"0.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c0.0\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"false")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"inf"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"inf"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u2018inf\u2019"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"nan"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"nan"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u2018nan\u2019"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"1e6"),(0,l.mdx)("td",{parentName:"tr",align:null},"1,000,000"),(0,l.mdx)("td",{parentName:"tr",align:null},"1e6"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u20181000000.0\u2019"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"foo"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"foo"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c\u201d (empty string)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c10\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"10"),(0,l.mdx)("td",{parentName:"tr",align:null},"10.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c10\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c10.0\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"10.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c10.0\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201ctrue\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201ctrue\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201cfalse\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201cfalse\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"false")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c","[1,2,3]","\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c","[1,2,3]","\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c{a:10}\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c{a:10}\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"1"),(0,l.mdx)("td",{parentName:"tr",align:null},"1.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201ctrue\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"0"),(0,l.mdx)("td",{parentName:"tr",align:null},"0.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201cfalse\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"false")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"[]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[]")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"[0,1,2]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[0,1,2]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[0.0,1.0,2.0]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[\u201c0\u201d,\u201d1\u201d,\u201d2\u201d]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[false,true,true]")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"[1,","[2]","]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[1,","[2]","]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[1.0,","[2.0]","]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[\u201c1\u201d,","[\u201c2\u201d]","]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[true,","[true]","]")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"[a,1]"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"[\u201ca\u201d,\u201d1\u201d]"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"{}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{}")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"{a:10}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:10}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:10.0}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:\u201d10\u201d}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a: true}")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"{a:","[0,1,2]","}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:","[0,1,2]","}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:","[0.0,1.0,2.-]","}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:","[\u201c0\u201d,\u201d1\u201d,\u201d2\u201d]","}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:","[false,true,true]","}")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"{a:10,b:xyz}"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:\u201d10\u201d,b:\u201dxyz\u201d}"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"choice(0,1)"),(0,l.mdx)("td",{parentName:"tr",align:null},"choice(0,1)"),(0,l.mdx)("td",{parentName:"tr",align:null},"choice(0.0,1.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"choice(\u201c0\u201d,\u201c1\u201d)"),(0,l.mdx)("td",{parentName:"tr",align:null},"choice(false,true)")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"choice(a,b)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"choice(\u201ca\u201d,\u201db\u201d)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"choice(1,a)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"choice(\u201c1\u201d,\u201da\u201d)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"interval(1.0, 2.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"interval(1, 2)"),(0,l.mdx)("td",{parentName:"tr",align:null},"interval(1.0, 2.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"interval(1, 2)"),(0,l.mdx)("td",{parentName:"tr",align:null},"interval(1, 2)"),(0,l.mdx)("td",{parentName:"tr",align:null},"interval(1.0, 2.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"range(1,10)"),(0,l.mdx)("td",{parentName:"tr",align:null},"range(1,10)"),(0,l.mdx)("td",{parentName:"tr",align:null},"range(1.0,10.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"range(1.0, 10.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"range(1,10)"),(0,l.mdx)("td",{parentName:"tr",align:null},"range(1.0,10.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")))))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2205f950.b90fc871.js b/assets/js/2205f950.b90fc871.js deleted file mode 100644 index 447ea860b0..0000000000 --- a/assets/js/2205f950.b90fc871.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[9938],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>s,MDXProvider:()=>d,mdx:()=>g,useMDXComponents:()=>c,withMDXComponents:()=>m});var r=t(96540);function a(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(a[t]=e[t]);return a}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(a[t]=e[t])}return a}var s=r.createContext({}),m=function(e){return function(n){var t=c(n.components);return r.createElement(e,i({},n,{components:t}))}},c=function(e){var n=r.useContext(s),t=n;return e&&(t="function"==typeof e?e(n):l(l({},n),e)),t},d=function(e){var n=c(e.components);return r.createElement(s.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},f=r.forwardRef((function(e,n){var t=e.components,a=e.mdxType,i=e.originalType,o=e.parentName,s=p(e,["components","mdxType","originalType","parentName"]),m=c(t),d=a,f=m["".concat(o,".").concat(d)]||m[d]||u[d]||i;return t?r.createElement(f,l(l({ref:n},s),{},{components:t})):r.createElement(f,l({ref:n},s))}));function g(e,n){var t=arguments,a=n&&n.mdxType;if("string"==typeof e||a){var i=t.length,o=new Array(i);o[0]=f;var l={};for(var p in n)hasOwnProperty.call(n,p)&&(l[p]=n[p]);l.originalType=e,l.mdxType="string"==typeof e?e:a,o[1]=l;for(var s=2;s{t.d(n,{A:()=>p,C:()=>s});var r=t(58168),a=t(96540),i=t(75489),o=t(44586),l=t(74098);function p(e){return a.createElement(i.default,(0,r.A)({},e,{to:(n=e.to,p=(0,l.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==p?void 0:p.name)?t:"current"]+n),target:"_blank"}));var n,t,p}function s(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return a.createElement(p,e,a.createElement("span",null,"\xa0"),a.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},20443:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>s,default:()=>u,frontMatter:()=>p,metadata:()=>m,toc:()=>c});var r=t(58168),a=t(98587),i=(t(96540),t(15680)),o=t(49595),l=["components"],p={id:"rerun",title:"Re-run a job from previous config",sidebar_label:"Re-run"},s=void 0,m={unversionedId:"experimental/rerun",id:"version-1.3/experimental/rerun",title:"Re-run a job from previous config",description:"This is an experimental feature. Please read through this page to understand what is supported.",source:"@site/versioned_docs/version-1.3/experimental/rerun.md",sourceDirName:"experimental",slug:"/experimental/rerun",permalink:"/docs/1.3/experimental/rerun",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/experimental/rerun.md",tags:[],version:"1.3",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"rerun",title:"Re-run a job from previous config",sidebar_label:"Re-run"},sidebar:"docs",previous:{title:"Callbacks",permalink:"/docs/1.3/experimental/callbacks"},next:{title:"Developer Guide Overview",permalink:"/docs/1.3/development/overview"}},c=[{value:"Important Notes",id:"important-notes",children:[],level:3}],d={toc:c};function u(e){var n=e.components,t=(0,a.A)(e,l);return(0,i.mdx)("wrapper",(0,r.A)({},d,t,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)(o.C,{text:"Example application",to:"examples/experimental/rerun",mdxType:"ExampleGithubLink"}),(0,i.mdx)("div",{className:"admonition admonition-caution alert alert--warning"},(0,i.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,i.mdx)("h5",{parentName:"div"},(0,i.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,i.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"16",height:"16",viewBox:"0 0 16 16"},(0,i.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"}))),"caution")),(0,i.mdx)("div",{parentName:"div",className:"admonition-content"},(0,i.mdx)("p",{parentName:"div"},"This is an experimental feature. Please read through this page to understand what is supported."))),(0,i.mdx)("p",null,"We use the example app linked above for demonstration. To save the configs for re-run, first use the experimental\nHydra Callback for saving the job info:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"hydra:\n callbacks:\n save_job_info:\n _target_: hydra.experimental.callbacks.PickleJobInfoCallback\n")),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Example function"',title:'"Example','function"':!0},'@hydra.main(version_base=None, config_path=".", config_name="config")\ndef my_app(cfg: DictConfig) -> None:\n log.info(f"output_dir={HydraConfig.get().runtime.output_dir}")\n log.info(f"cfg.foo={cfg.foo}")\n')),(0,i.mdx)("p",null,"Run the example app:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ python my_app.py\n[2022-03-16 14:51:30,905][hydra.experimental.pickle_job_info_callback][INFO] - Saving job configs in /Users/jieru/workspace/hydra/examples/experimental/outputs/2022-03-16/14-51-30/.hydra/config.pickle\n[2022-03-16 14:51:30,906][__main__][INFO] - Output_dir=/Users/jieru/workspace/hydra/examples/experimental/outputs/2022-03-16/14-51-30\n[2022-03-16 14:51:30,906][__main__][INFO] - cfg.foo=bar\n[2022-03-16 14:51:30,906][hydra.experimental.pickle_job_info_callback][INFO] - Saving job_return in /Users/jieru/workspace/hydra/examples/experimental/outputs/2022-03-16/14-51-30/.hydra/job_return.pickle\n")),(0,i.mdx)("p",null,"The Callback saves ",(0,i.mdx)("inlineCode",{parentName:"p"},"config.pickle")," in ",(0,i.mdx)("inlineCode",{parentName:"p"},".hydra")," sub dir, this is what we will use for rerun."),(0,i.mdx)("p",null,"Now rerun the app"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ OUTPUT_DIR=/Users/jieru/workspace/hydra/examples/experimental/outputs/2022-03-16/14-51-30/.hydra/\n$ python my_app.py --experimental-rerun $OUTPUT_DIR/config.pickle\n/Users/jieru/workspace/hydra/hydra/main.py:23: UserWarning: Experimental rerun CLI option.\n warnings.warn(msg, UserWarning)\n[2022-03-16 14:59:21,666][__main__][INFO] - Output_dir=/Users/jieru/workspace/hydra/examples/experimental/outputs/2022-03-16/14-51-30\n[2022-03-16 14:59:21,666][__main__][INFO] - cfg.foo=bar\n")),(0,i.mdx)("p",null,"You will notice ",(0,i.mdx)("inlineCode",{parentName:"p"},"my_app.log")," is updated with the logging from the second run, but Callbacks are not called this time. Read on to learn more."),(0,i.mdx)("h3",{id:"important-notes"},"Important Notes"),(0,i.mdx)("p",null,"This is an experimental feature. Please reach out if you have any question. "),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"Only single run is supported."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"--experimental-rerun")," cannot be used with other command-line options or overrides. They will simply be ignored."),(0,i.mdx)("li",{parentName:"ul"},"Rerun passes in a cfg_passthrough directly to your application, this means except for logging, no other ",(0,i.mdx)("inlineCode",{parentName:"li"},"hydra.main"),"\nfunctions are called (such as change working dir, or calling callbacks.) "),(0,i.mdx)("li",{parentName:"ul"},"The configs are preserved and reconstructed to the best efforts. Meaning we can only guarantee that the ",(0,i.mdx)("inlineCode",{parentName:"li"},"cfg")," object\nitself passed in by ",(0,i.mdx)("inlineCode",{parentName:"li"},"hydra.main")," stays the same across runs. However, configs are resolved lazily. Meaning we cannot\nguarantee your application will behave the same if your application resolves configs during run time. In the following example,\n",(0,i.mdx)("inlineCode",{parentName:"li"},"cfg.time_now")," will resolve to different value every run.")),(0,i.mdx)("div",{className:"row"},(0,i.mdx)("div",{className:"col col--5"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"time_now: ${now:%H-%M-%S}\n\n\n\n"))),(0,i.mdx)("div",{className:"col col--7"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Example function"',title:'"Example','function"':!0},'@hydra.main(version_base=None, config_path=".", config_name="config")\ndef my_app(cfg: DictConfig) -> None:\n val = cfg.time_now\n # the rest of the application\n')))))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2205f950.f39b465b.js b/assets/js/2205f950.f39b465b.js new file mode 100644 index 0000000000..80cefe956a --- /dev/null +++ b/assets/js/2205f950.f39b465b.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[9938],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>s,MDXProvider:()=>d,mdx:()=>g,useMDXComponents:()=>c,withMDXComponents:()=>m});var r=t(96540);function a(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(a[t]=e[t]);return a}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(a[t]=e[t])}return a}var s=r.createContext({}),m=function(e){return function(n){var t=c(n.components);return r.createElement(e,i({},n,{components:t}))}},c=function(e){var n=r.useContext(s),t=n;return e&&(t="function"==typeof e?e(n):l(l({},n),e)),t},d=function(e){var n=c(e.components);return r.createElement(s.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},f=r.forwardRef((function(e,n){var t=e.components,a=e.mdxType,i=e.originalType,o=e.parentName,s=p(e,["components","mdxType","originalType","parentName"]),m=c(t),d=a,f=m["".concat(o,".").concat(d)]||m[d]||u[d]||i;return t?r.createElement(f,l(l({ref:n},s),{},{components:t})):r.createElement(f,l({ref:n},s))}));function g(e,n){var t=arguments,a=n&&n.mdxType;if("string"==typeof e||a){var i=t.length,o=new Array(i);o[0]=f;var l={};for(var p in n)hasOwnProperty.call(n,p)&&(l[p]=n[p]);l.originalType=e,l.mdxType="string"==typeof e?e:a,o[1]=l;for(var s=2;s{t.d(n,{A:()=>p,C:()=>s});var r=t(58168),a=t(96540),i=t(75489),o=t(44586),l=t(74098);function p(e){return a.createElement(i.default,(0,r.A)({},e,{to:(n=e.to,p=(0,l.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==p?void 0:p.name)?t:"current"]+n),target:"_blank"}));var n,t,p}function s(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return a.createElement(p,e,a.createElement("span",null,"\xa0"),a.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},20443:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>s,default:()=>u,frontMatter:()=>p,metadata:()=>m,toc:()=>c});var r=t(58168),a=t(98587),i=(t(96540),t(15680)),o=t(49595),l=["components"],p={id:"rerun",title:"Re-run a job from previous config",sidebar_label:"Re-run"},s=void 0,m={unversionedId:"experimental/rerun",id:"version-1.3/experimental/rerun",title:"Re-run a job from previous config",description:"This is an experimental feature. Please read through this page to understand what is supported.",source:"@site/versioned_docs/version-1.3/experimental/rerun.md",sourceDirName:"experimental",slug:"/experimental/rerun",permalink:"/docs/1.3/experimental/rerun",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/experimental/rerun.md",tags:[],version:"1.3",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"rerun",title:"Re-run a job from previous config",sidebar_label:"Re-run"},sidebar:"docs",previous:{title:"Callbacks",permalink:"/docs/1.3/experimental/callbacks"},next:{title:"Developer Guide Overview",permalink:"/docs/1.3/development/overview"}},c=[{value:"Important Notes",id:"important-notes",children:[],level:3}],d={toc:c};function u(e){var n=e.components,t=(0,a.A)(e,l);return(0,i.mdx)("wrapper",(0,r.A)({},d,t,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)(o.C,{text:"Example application",to:"examples/experimental/rerun",mdxType:"ExampleGithubLink"}),(0,i.mdx)("div",{className:"admonition admonition-caution alert alert--warning"},(0,i.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,i.mdx)("h5",{parentName:"div"},(0,i.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,i.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"16",height:"16",viewBox:"0 0 16 16"},(0,i.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"}))),"caution")),(0,i.mdx)("div",{parentName:"div",className:"admonition-content"},(0,i.mdx)("p",{parentName:"div"},"This is an experimental feature. Please read through this page to understand what is supported."))),(0,i.mdx)("p",null,"We use the example app linked above for demonstration. To save the configs for re-run, first use the experimental\nHydra Callback for saving the job info:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"hydra:\n callbacks:\n save_job_info:\n _target_: hydra.experimental.callbacks.PickleJobInfoCallback\n")),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Example function"',title:'"Example','function"':!0},'@hydra.main(version_base=None, config_path=".", config_name="config")\ndef my_app(cfg: DictConfig) -> None:\n log.info(f"output_dir={HydraConfig.get().runtime.output_dir}")\n log.info(f"cfg.foo={cfg.foo}")\n')),(0,i.mdx)("p",null,"Run the example app:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ python my_app.py\n[2022-03-16 14:51:30,905][hydra.experimental.pickle_job_info_callback][INFO] - Saving job configs in /Users/jieru/workspace/hydra/examples/experimental/outputs/2022-03-16/14-51-30/.hydra/config.pickle\n[2022-03-16 14:51:30,906][__main__][INFO] - Output_dir=/Users/jieru/workspace/hydra/examples/experimental/outputs/2022-03-16/14-51-30\n[2022-03-16 14:51:30,906][__main__][INFO] - cfg.foo=bar\n[2022-03-16 14:51:30,906][hydra.experimental.pickle_job_info_callback][INFO] - Saving job_return in /Users/jieru/workspace/hydra/examples/experimental/outputs/2022-03-16/14-51-30/.hydra/job_return.pickle\n")),(0,i.mdx)("p",null,"The Callback saves ",(0,i.mdx)("inlineCode",{parentName:"p"},"config.pickle")," in ",(0,i.mdx)("inlineCode",{parentName:"p"},".hydra")," sub dir, this is what we will use for rerun."),(0,i.mdx)("p",null,"Now rerun the app"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ OUTPUT_DIR=/Users/jieru/workspace/hydra/examples/experimental/outputs/2022-03-16/14-51-30/.hydra/\n$ python my_app.py --experimental-rerun $OUTPUT_DIR/config.pickle\n/Users/jieru/workspace/hydra/hydra/main.py:23: UserWarning: Experimental rerun CLI option.\n warnings.warn(msg, UserWarning)\n[2022-03-16 14:59:21,666][__main__][INFO] - Output_dir=/Users/jieru/workspace/hydra/examples/experimental/outputs/2022-03-16/14-51-30\n[2022-03-16 14:59:21,666][__main__][INFO] - cfg.foo=bar\n")),(0,i.mdx)("p",null,"You will notice ",(0,i.mdx)("inlineCode",{parentName:"p"},"my_app.log")," is updated with the logging from the second run, but Callbacks are not called this time. Read on to learn more."),(0,i.mdx)("h3",{id:"important-notes"},"Important Notes"),(0,i.mdx)("p",null,"This is an experimental feature. Please reach out if you have any question. "),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"Only single run is supported."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"--experimental-rerun")," cannot be used with other command-line options or overrides. They will simply be ignored."),(0,i.mdx)("li",{parentName:"ul"},"Rerun passes in a cfg_passthrough directly to your application, this means except for logging, no other ",(0,i.mdx)("inlineCode",{parentName:"li"},"hydra.main"),"\nfunctions are called (such as change working dir, or calling callbacks.) "),(0,i.mdx)("li",{parentName:"ul"},"The configs are preserved and reconstructed to the best efforts. Meaning we can only guarantee that the ",(0,i.mdx)("inlineCode",{parentName:"li"},"cfg")," object\nitself passed in by ",(0,i.mdx)("inlineCode",{parentName:"li"},"hydra.main")," stays the same across runs. However, configs are resolved lazily. Meaning we cannot\nguarantee your application will behave the same if your application resolves configs during run time. In the following example,\n",(0,i.mdx)("inlineCode",{parentName:"li"},"cfg.time_now")," will resolve to different value every run.")),(0,i.mdx)("div",{className:"row"},(0,i.mdx)("div",{className:"col col--5"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"time_now: ${now:%H-%M-%S}\n\n\n\n"))),(0,i.mdx)("div",{className:"col col--7"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Example function"',title:'"Example','function"':!0},'@hydra.main(version_base=None, config_path=".", config_name="config")\ndef my_app(cfg: DictConfig) -> None:\n val = cfg.time_now\n # the rest of the application\n')))))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/22abb723.1382d556.js b/assets/js/22abb723.1382d556.js new file mode 100644 index 0000000000..c330956e54 --- /dev/null +++ b/assets/js/22abb723.1382d556.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[5774],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>l,MDXProvider:()=>f,mdx:()=>g,useMDXComponents:()=>u,withMDXComponents:()=>p});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var l=r.createContext({}),p=function(e){return function(t){var n=u(t.components);return r.createElement(e,a({},t,{components:n}))}},u=function(e){var t=r.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):s(s({},t),e)),n},f=function(e){var t=u(e.components);return r.createElement(l.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},d=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,l=c(e,["components","mdxType","originalType","parentName"]),p=u(n),f=o,d=p["".concat(i,".").concat(f)]||p[f]||m[f]||a;return n?r.createElement(d,s(s({ref:t},l),{},{components:n})):r.createElement(d,s({ref:t},l))}));function g(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=n.length,i=new Array(a);i[0]=d;var s={};for(var c in t)hasOwnProperty.call(t,c)&&(s[c]=t[c]);s.originalType=e,s.mdxType="string"==typeof e?e:o,i[1]=s;for(var l=2;l{n.d(t,{A:()=>c,C:()=>l});var r=n(58168),o=n(96540),a=n(75489),i=n(44586),s=n(74098);function c(e){return o.createElement(a.default,(0,r.A)({},e,{to:(t=e.to,c=(0,s.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==c?void 0:c.name)?n:"current"]+t),target:"_blank"}));var t,n,c}function l(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return o.createElement(c,e,o.createElement("span",null,"\xa0"),o.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},96597:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>l,default:()=>m,frontMatter:()=>c,metadata:()=>p,toc:()=>u});var r=n(58168),o=n(98587),a=(n(96540),n(15680)),i=n(49595),s=["components"],c={id:"using_config",title:"Using the config object"},l=void 0,p={unversionedId:"tutorials/basic/your_first_app/using_config",id:"tutorials/basic/your_first_app/using_config",title:"Using the config object",description:"Here are some basic features of the Hydra Configuration Object:",source:"@site/docs/tutorials/basic/your_first_app/3_using_config.md",sourceDirName:"tutorials/basic/your_first_app",slug:"/tutorials/basic/your_first_app/using_config",permalink:"/docs/tutorials/basic/your_first_app/using_config",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/tutorials/basic/your_first_app/3_using_config.md",tags:[],version:"current",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:3,frontMatter:{id:"using_config",title:"Using the config object"},sidebar:"docs",previous:{title:"Specifying a config file",permalink:"/docs/tutorials/basic/your_first_app/config_file"},next:{title:"Grouping config files",permalink:"/docs/tutorials/basic/your_first_app/config_groups"}},u=[],f={toc:u};function m(e){var t=e.components,n=(0,o.A)(e,s);return(0,a.mdx)("wrapper",(0,r.A)({},f,n,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)(i.C,{to:"examples/tutorials/basic/your_first_hydra_app/3_using_config",mdxType:"ExampleGithubLink"}),(0,a.mdx)("p",null,"Here are some basic features of the Hydra Configuration Object:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},'node: # Config is hierarchical\n loompa: 10 # Simple value\n zippity: ${node.loompa} # Value interpolation\n do: "oompa ${node.loompa}" # String interpolation\n waldo: ??? # Missing value, must be populated prior to access\n')),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="main.py"',title:'"main.py"'},'from omegaconf import DictConfig, OmegaConf\nimport hydra\n\n@hydra.main(version_base=None, config_path=".", config_name="config")\ndef my_app(cfg: DictConfig):\n assert cfg.node.loompa == 10 # attribute style access\n assert cfg["node"]["loompa"] == 10 # dictionary style access\n\n assert cfg.node.zippity == 10 # Value interpolation\n assert isinstance(cfg.node.zippity, int) # Value interpolation type\n assert cfg.node.do == "oompa 10" # string interpolation\n\n cfg.node.waldo # raises an exception\n\nif __name__ == "__main__":\n my_app()\n')),(0,a.mdx)("p",null,"Outputs:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre"},'$ python my_app.py \nTraceback (most recent call last):\n File "my_app.py", line 32, in my_app\n cfg.node.waldo\nomegaconf.errors.MissingMandatoryValue: Missing mandatory value: node.waldo\n full_key: node.waldo\n object_type=dict\n')),(0,a.mdx)("p",null,"Hydra's configuration object is an instance of OmegaConf's DictConfig.\nYou can learn more about OmegaConf ",(0,a.mdx)("a",{class:"external",href:"https://omegaconf.readthedocs.io/en/latest/usage.html#access-and-manipulation",target:"_blank"},"here"),"."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/22abb723.38636b2f.js b/assets/js/22abb723.38636b2f.js deleted file mode 100644 index a27366644e..0000000000 --- a/assets/js/22abb723.38636b2f.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[5774],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>l,MDXProvider:()=>f,mdx:()=>g,useMDXComponents:()=>u,withMDXComponents:()=>p});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var l=r.createContext({}),p=function(e){return function(t){var n=u(t.components);return r.createElement(e,a({},t,{components:n}))}},u=function(e){var t=r.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):c(c({},t),e)),n},f=function(e){var t=u(e.components);return r.createElement(l.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},d=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,l=s(e,["components","mdxType","originalType","parentName"]),p=u(n),f=o,d=p["".concat(i,".").concat(f)]||p[f]||m[f]||a;return n?r.createElement(d,c(c({ref:t},l),{},{components:n})):r.createElement(d,c({ref:t},l))}));function g(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=n.length,i=new Array(a);i[0]=d;var c={};for(var s in t)hasOwnProperty.call(t,s)&&(c[s]=t[s]);c.originalType=e,c.mdxType="string"==typeof e?e:o,i[1]=c;for(var l=2;l{n.d(t,{A:()=>s,C:()=>l});var r=n(58168),o=n(96540),a=n(75489),i=n(44586),c=n(74098);function s(e){return o.createElement(a.default,(0,r.A)({},e,{to:(t=e.to,s=(0,c.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==s?void 0:s.name)?n:"current"]+t),target:"_blank"}));var t,n,s}function l(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return o.createElement(s,e,o.createElement("span",null,"\xa0"),o.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},96597:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>l,default:()=>m,frontMatter:()=>s,metadata:()=>p,toc:()=>u});var r=n(58168),o=n(98587),a=(n(96540),n(15680)),i=n(49595),c=["components"],s={id:"using_config",title:"Using the config object"},l=void 0,p={unversionedId:"tutorials/basic/your_first_app/using_config",id:"tutorials/basic/your_first_app/using_config",title:"Using the config object",description:"Here are some basic features of the Hydra Configuration Object:",source:"@site/docs/tutorials/basic/your_first_app/3_using_config.md",sourceDirName:"tutorials/basic/your_first_app",slug:"/tutorials/basic/your_first_app/using_config",permalink:"/docs/tutorials/basic/your_first_app/using_config",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/tutorials/basic/your_first_app/3_using_config.md",tags:[],version:"current",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:3,frontMatter:{id:"using_config",title:"Using the config object"},sidebar:"docs",previous:{title:"Specifying a config file",permalink:"/docs/tutorials/basic/your_first_app/config_file"},next:{title:"Grouping config files",permalink:"/docs/tutorials/basic/your_first_app/config_groups"}},u=[],f={toc:u};function m(e){var t=e.components,n=(0,o.A)(e,c);return(0,a.mdx)("wrapper",(0,r.A)({},f,n,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)(i.C,{to:"examples/tutorials/basic/your_first_hydra_app/3_using_config",mdxType:"ExampleGithubLink"}),(0,a.mdx)("p",null,"Here are some basic features of the Hydra Configuration Object:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},'node: # Config is hierarchical\n loompa: 10 # Simple value\n zippity: ${node.loompa} # Value interpolation\n do: "oompa ${node.loompa}" # String interpolation\n waldo: ??? # Missing value, must be populated prior to access\n')),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="main.py"',title:'"main.py"'},'from omegaconf import DictConfig, OmegaConf\nimport hydra\n\n@hydra.main(version_base=None, config_path=".", config_name="config")\ndef my_app(cfg: DictConfig):\n assert cfg.node.loompa == 10 # attribute style access\n assert cfg["node"]["loompa"] == 10 # dictionary style access\n\n assert cfg.node.zippity == 10 # Value interpolation\n assert isinstance(cfg.node.zippity, int) # Value interpolation type\n assert cfg.node.do == "oompa 10" # string interpolation\n\n cfg.node.waldo # raises an exception\n\nif __name__ == "__main__":\n my_app()\n')),(0,a.mdx)("p",null,"Outputs:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre"},'$ python my_app.py \nTraceback (most recent call last):\n File "my_app.py", line 32, in my_app\n cfg.node.waldo\nomegaconf.errors.MissingMandatoryValue: Missing mandatory value: node.waldo\n full_key: node.waldo\n object_type=dict\n')),(0,a.mdx)("p",null,"Hydra's configuration object is an instance of OmegaConf's DictConfig.\nYou can learn more about OmegaConf ",(0,a.mdx)("a",{class:"external",href:"https://omegaconf.readthedocs.io/en/latest/usage.html#access-and-manipulation",target:"_blank"},"here"),"."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2380203e.44404c19.js b/assets/js/2380203e.44404c19.js new file mode 100644 index 0000000000..73508bbce9 --- /dev/null +++ b/assets/js/2380203e.44404c19.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[6388],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>s,MDXProvider:()=>m,mdx:()=>g,useMDXComponents:()=>d,withMDXComponents:()=>p});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var s=r.createContext({}),p=function(e){return function(t){var n=d(t.components);return r.createElement(e,a({},t,{components:n}))}},d=function(e){var t=r.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):c(c({},t),e)),n},m=function(e){var t=d(e.components);return r.createElement(s.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},f=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,s=l(e,["components","mdxType","originalType","parentName"]),p=d(n),m=o,f=p["".concat(i,".").concat(m)]||p[m]||u[m]||a;return n?r.createElement(f,c(c({ref:t},s),{},{components:n})):r.createElement(f,c({ref:t},s))}));function g(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=n.length,i=new Array(a);i[0]=f;var c={};for(var l in t)hasOwnProperty.call(t,l)&&(c[l]=t[l]);c.originalType=e,c.mdxType="string"==typeof e?e:o,i[1]=c;for(var s=2;s{n.r(t),n.d(t,{contentTitle:()=>l,default:()=>m,frontMatter:()=>c,metadata:()=>s,toc:()=>p});var r=n(58168),o=n(98587),a=(n(96540),n(15680)),i=["components"],c={id:"write_protect_config_node",title:"Read-only config"},l=void 0,s={unversionedId:"patterns/write_protect_config_node",id:"version-1.0/patterns/write_protect_config_node",title:"Read-only config",description:"Example application",source:"@site/versioned_docs/version-1.0/patterns/write_protect_config_node.md",sourceDirName:"patterns",slug:"/patterns/write_protect_config_node",permalink:"/docs/1.0/patterns/write_protect_config_node",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.0/patterns/write_protect_config_node.md",tags:[],version:"1.0",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"write_protect_config_node",title:"Read-only config"},sidebar:"version-1.0/docs",previous:{title:"Specializing configuration",permalink:"/docs/1.0/patterns/specializing_config"},next:{title:"Introduction",permalink:"/docs/1.0/configure_hydra/intro"}},p=[{value:"Problem",id:"problem",children:[],level:3},{value:"Solution",id:"solution",children:[],level:3}],d={toc:p};function m(e){var t=e.components,n=(0,o.A)(e,i);return(0,a.mdx)("wrapper",(0,r.A)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)("p",null,(0,a.mdx)("a",{parentName:"p",href:"https://github.com/facebookresearch/hydra/tree/1.0_branch/examples/patterns/write_protect_config_node"},(0,a.mdx)("img",{parentName:"a",src:"https://img.shields.io/badge/-Example%20application-informational",alt:"Example application"}))),(0,a.mdx)("h3",{id:"problem"},"Problem"),(0,a.mdx)("p",null,"Sometimes you want to prevent a config node from being changed accidentally."),(0,a.mdx)("h3",{id:"solution"},"Solution"),(0,a.mdx)("p",null,"Structured Configs can enable it by passing ",(0,a.mdx)("a",{parentName:"p",href:"https://omegaconf.readthedocs.io/en/latest/structured_config.html#frozen"},"frozen=True")," in the dataclass definition.\nUsing Structured Configs, you can annotate a dataclass as frozen. This is recursive and applies to all child nodes."),(0,a.mdx)("p",null,"This will prevent modifications via code, command line overrides and config composition."),(0,a.mdx)("div",{className:"row"},(0,a.mdx)("div",{className:"col col--6"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="frozen.py" {1}',title:'"frozen.py"',"{1}":!0},'@dataclass(frozen=True)\nclass SerialPort:\n baud_rate: int = 19200\n data_bits: int = 8\n stop_bits: int = 1\n\n\ncs = ConfigStore.instance()\ncs.store(name="config", node=SerialPort)\n\n\n@hydra.main(config_name="config")\ndef my_app(cfg: SerialPort) -> None:\n print(cfg)\n\n\nif __name__ == "__main__":\n my_app()\n'))),(0,a.mdx)("div",{className:"col col--6"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-shell",metastring:'script title="Output"',script:!0,title:'"Output"'},"$ python frozen.py data_bits=10\nError merging override data_bits=10\nCannot change read-only config container\n full_key: data_bits\n reference_type=Optional[SerialPort]\n object_type=SerialPort\n")))),(0,a.mdx)("div",{class:"alert alert--warning",role:"alert"},(0,a.mdx)("strong",null,"NOTE"),": A crafty user can find many ways around this. this is just making it harder to change things accidentally."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2380203e.78f9f44a.js b/assets/js/2380203e.78f9f44a.js deleted file mode 100644 index 4f271d40f2..0000000000 --- a/assets/js/2380203e.78f9f44a.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[6388],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>s,MDXProvider:()=>m,mdx:()=>g,useMDXComponents:()=>d,withMDXComponents:()=>p});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var s=r.createContext({}),p=function(e){return function(t){var n=d(t.components);return r.createElement(e,a({},t,{components:n}))}},d=function(e){var t=r.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):c(c({},t),e)),n},m=function(e){var t=d(e.components);return r.createElement(s.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},f=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,s=l(e,["components","mdxType","originalType","parentName"]),p=d(n),m=o,f=p["".concat(i,".").concat(m)]||p[m]||u[m]||a;return n?r.createElement(f,c(c({ref:t},s),{},{components:n})):r.createElement(f,c({ref:t},s))}));function g(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=n.length,i=new Array(a);i[0]=f;var c={};for(var l in t)hasOwnProperty.call(t,l)&&(c[l]=t[l]);c.originalType=e,c.mdxType="string"==typeof e?e:o,i[1]=c;for(var s=2;s{n.r(t),n.d(t,{contentTitle:()=>l,default:()=>m,frontMatter:()=>c,metadata:()=>s,toc:()=>p});var r=n(58168),o=n(98587),a=(n(96540),n(15680)),i=["components"],c={id:"write_protect_config_node",title:"Read-only config"},l=void 0,s={unversionedId:"patterns/write_protect_config_node",id:"version-1.0/patterns/write_protect_config_node",title:"Read-only config",description:"Example application",source:"@site/versioned_docs/version-1.0/patterns/write_protect_config_node.md",sourceDirName:"patterns",slug:"/patterns/write_protect_config_node",permalink:"/docs/1.0/patterns/write_protect_config_node",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.0/patterns/write_protect_config_node.md",tags:[],version:"1.0",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"write_protect_config_node",title:"Read-only config"},sidebar:"version-1.0/docs",previous:{title:"Specializing configuration",permalink:"/docs/1.0/patterns/specializing_config"},next:{title:"Introduction",permalink:"/docs/1.0/configure_hydra/intro"}},p=[{value:"Problem",id:"problem",children:[],level:3},{value:"Solution",id:"solution",children:[],level:3}],d={toc:p};function m(e){var t=e.components,n=(0,o.A)(e,i);return(0,a.mdx)("wrapper",(0,r.A)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)("p",null,(0,a.mdx)("a",{parentName:"p",href:"https://github.com/facebookresearch/hydra/tree/1.0_branch/examples/patterns/write_protect_config_node"},(0,a.mdx)("img",{parentName:"a",src:"https://img.shields.io/badge/-Example%20application-informational",alt:"Example application"}))),(0,a.mdx)("h3",{id:"problem"},"Problem"),(0,a.mdx)("p",null,"Sometimes you want to prevent a config node from being changed accidentally."),(0,a.mdx)("h3",{id:"solution"},"Solution"),(0,a.mdx)("p",null,"Structured Configs can enable it by passing ",(0,a.mdx)("a",{parentName:"p",href:"https://omegaconf.readthedocs.io/en/latest/structured_config.html#frozen"},"frozen=True")," in the dataclass definition.\nUsing Structured Configs, you can annotate a dataclass as frozen. This is recursive and applies to all child nodes."),(0,a.mdx)("p",null,"This will prevent modifications via code, command line overrides and config composition."),(0,a.mdx)("div",{className:"row"},(0,a.mdx)("div",{className:"col col--6"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="frozen.py" {1}',title:'"frozen.py"',"{1}":!0},'@dataclass(frozen=True)\nclass SerialPort:\n baud_rate: int = 19200\n data_bits: int = 8\n stop_bits: int = 1\n\n\ncs = ConfigStore.instance()\ncs.store(name="config", node=SerialPort)\n\n\n@hydra.main(config_name="config")\ndef my_app(cfg: SerialPort) -> None:\n print(cfg)\n\n\nif __name__ == "__main__":\n my_app()\n'))),(0,a.mdx)("div",{className:"col col--6"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-shell",metastring:'script title="Output"',script:!0,title:'"Output"'},"$ python frozen.py data_bits=10\nError merging override data_bits=10\nCannot change read-only config container\n full_key: data_bits\n reference_type=Optional[SerialPort]\n object_type=SerialPort\n")))),(0,a.mdx)("div",{class:"alert alert--warning",role:"alert"},(0,a.mdx)("strong",null,"NOTE"),": A crafty user can find many ways around this. this is just making it harder to change things accidentally."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/240de8c7.45082967.js b/assets/js/240de8c7.45082967.js new file mode 100644 index 0000000000..322ab1a0b3 --- /dev/null +++ b/assets/js/240de8c7.45082967.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[1132],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>p,MDXProvider:()=>m,mdx:()=>f,useMDXComponents:()=>d,withMDXComponents:()=>c});var o=t(96540);function r(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function a(){return a=Object.assign||function(e){for(var n=1;n=0||(r[t]=e[t]);return r}(e,n);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(o=0;o=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(r[t]=e[t])}return r}var p=o.createContext({}),c=function(e){return function(n){var t=d(n.components);return o.createElement(e,a({},n,{components:t}))}},d=function(e){var n=o.useContext(p),t=n;return e&&(t="function"==typeof e?e(n):s(s({},n),e)),t},m=function(e){var n=d(e.components);return o.createElement(p.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return o.createElement(o.Fragment,{},n)}},g=o.forwardRef((function(e,n){var t=e.components,r=e.mdxType,a=e.originalType,i=e.parentName,p=l(e,["components","mdxType","originalType","parentName"]),c=d(t),m=r,g=c["".concat(i,".").concat(m)]||c[m]||u[m]||a;return t?o.createElement(g,s(s({ref:n},p),{},{components:t})):o.createElement(g,s({ref:n},p))}));function f(e,n){var t=arguments,r=n&&n.mdxType;if("string"==typeof e||r){var a=t.length,i=new Array(a);i[0]=g;var s={};for(var l in n)hasOwnProperty.call(n,l)&&(s[l]=n[l]);s.originalType=e,s.mdxType="string"==typeof e?e:r,i[1]=s;for(var p=2;p{t.r(n),t.d(n,{contentTitle:()=>l,default:()=>m,frontMatter:()=>s,metadata:()=>p,toc:()=>c});var o=t(58168),r=t(98587),a=(t(96540),t(15680)),i=["components"],s={id:"config_store",title:"Config Store API"},l=void 0,p={unversionedId:"tutorials/structured_config/config_store",id:"version-1.3/tutorials/structured_config/config_store",title:"Config Store API",description:"Throughout the rest of tutorials, we will be using ConfigStore to register dataclasses as input configs in Hydra.",source:"@site/versioned_docs/version-1.3/tutorials/structured_config/10_config_store.md",sourceDirName:"tutorials/structured_config",slug:"/tutorials/structured_config/config_store",permalink:"/docs/1.3/tutorials/structured_config/config_store",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/tutorials/structured_config/10_config_store.md",tags:[],version:"1.3",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:10,frontMatter:{id:"config_store",title:"Config Store API"},sidebar:"docs",previous:{title:"Introduction to Structured Configs",permalink:"/docs/1.3/tutorials/structured_config/intro"},next:{title:"Minimal example",permalink:"/docs/1.3/tutorials/structured_config/minimal_example"}},c=[{value:"API",id:"api",children:[],level:3},{value:"ConfigStore and YAML input configs",id:"configstore-and-yaml-input-configs",children:[],level:3},{value:"Example node values",id:"example-node-values",children:[],level:3}],d={toc:c};function m(e){var n=e.components,t=(0,r.A)(e,i);return(0,a.mdx)("wrapper",(0,o.A)({},d,t,{components:n,mdxType:"MDXLayout"}),(0,a.mdx)("p",null,"Throughout the rest of tutorials, we will be using ",(0,a.mdx)("inlineCode",{parentName:"p"},"ConfigStore")," to register dataclasses as input configs in Hydra.\n",(0,a.mdx)("inlineCode",{parentName:"p"},"ConfigStore")," is a singleton storing configs in memory.\nThe primary API for interacting with the ",(0,a.mdx)("inlineCode",{parentName:"p"},"ConfigStore")," is the store method described below."),(0,a.mdx)("h3",{id:"api"},"API"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python"},'class ConfigStore(metaclass=Singleton):\n def store(\n self,\n name: str,\n node: Any,\n group: Optional[str] = None,\n package: Optional[str] = "_group_",\n provider: Optional[str] = None,\n ) -> None:\n """\n Stores a config node into the repository\n :param name: config name\n :param node: config node, can be DictConfig, ListConfig,\n Structured configs and even dict and list\n :param group: config group, subgroup separator is \'/\',\n for example hydra/launcher\n :param package: Config node parent hierarchy.\n Child separator is \'.\', for example foo.bar.baz\n :param provider: the name of the module/app providing this config.\n Helps debugging.\n """\n ...\n')),(0,a.mdx)("h3",{id:"configstore-and-yaml-input-configs"},"ConfigStore and YAML input configs"),(0,a.mdx)("p",null,(0,a.mdx)("inlineCode",{parentName:"p"},"ConfigStore")," has feature parity with YAML input configs. On top of that, it also provides typing validation.\n",(0,a.mdx)("inlineCode",{parentName:"p"},"ConfigStore")," can be used alone or together with YAML. We will see more examples later in this series of tutorials.\nFor now, let's see how the ",(0,a.mdx)("inlineCode",{parentName:"p"},"ConfigStore")," API translates into the YAML input configs, which we've become more familiar\nwith after the basic tutorials."),(0,a.mdx)("p",null,"Say we have a simple application and a ",(0,a.mdx)("inlineCode",{parentName:"p"},"db")," config group with a ",(0,a.mdx)("inlineCode",{parentName:"p"},"mysql")," option:"),(0,a.mdx)("div",{className:"row"},(0,a.mdx)("div",{className:"col col--5"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app.py"',title:'"my_app.py"'},'@hydra.main(version_base=None, config_path="conf")\ndef my_app(cfg: DictConfig) -> None:\n print(OmegaConf.to_yaml(cfg))\n\n\nif __name__ == "__main__":\n my_app()\n'))),(0,a.mdx)("div",{className:"col col--4"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Directory layout"',title:'"Directory','layout"':!0},"\u251c\u2500 conf\n\u2502 \u2514\u2500 db\n\u2502 \u2514\u2500 mysql.yaml\n\u2514\u2500\u2500 my_app.py\n\n\n\n"))),(0,a.mdx)("div",{className:"col col--3"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml"',title:'"db/mysql.yaml"'},"driver: mysql\nuser: omry\npassword: secret\n\n\n\n\n")))),(0,a.mdx)("p",null,"What if we want to add an ",(0,a.mdx)("inlineCode",{parentName:"p"},"postgresql")," option now? Yes, we can easily add a ",(0,a.mdx)("inlineCode",{parentName:"p"},"db/postgresql.yaml")," config group option. But\nthat is not the only way! We can also use ",(0,a.mdx)("inlineCode",{parentName:"p"},"ConfigStore")," to make another config group option for ",(0,a.mdx)("inlineCode",{parentName:"p"},"db")," available to Hydra."),(0,a.mdx)("p",null,"To achieve this, we add a few lines (highlighted) in the above ",(0,a.mdx)("inlineCode",{parentName:"p"},"my_app.py")," file:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app.py" {1-9}',title:'"my_app.py"',"{1-9}":!0},'@dataclass\nclass PostgresSQLConfig:\n driver: str = "postgresql"\n user: str = "jieru"\n password: str = "secret"\n\ncs = ConfigStore.instance()\n# Registering the Config class with the name `postgresql` with the config group `db`\ncs.store(name="postgresql", group="db", node=PostgresSQLConfig)\n\n@hydra.main(version_base=None, config_path="conf")\ndef my_app(cfg: DictConfig) -> None:\n print(OmegaConf.to_yaml(cfg))\n\n\nif __name__ == "__main__":\n my_app()\n')),(0,a.mdx)("p",null,"Now that our application has access to both ",(0,a.mdx)("inlineCode",{parentName:"p"},"db")," config group options, let's run the application to verify:"),(0,a.mdx)("div",{className:"row"},(0,a.mdx)("div",{className:"col col--6"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-commandline",metastring:'title="python my_app.py +db=mysql"',title:'"python',"my_app.py":!0,"+db":'mysql"'},"db:\n driver: mysql\n user: omry\n password: secret\n\n"))),(0,a.mdx)("div",{className:"col col--6"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-commandline",metastring:'title="python my_app.py +db=postgresql"',title:'"python',"my_app.py":!0,"+db":'postgresql"'},"db:\n driver: postgresql\n user: jieru\n password: secret\n\n")))),(0,a.mdx)("h3",{id:"example-node-values"},"Example node values"),(0,a.mdx)("p",null,"A few examples of supported node values parameters:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python"},'from dataclasses import dataclass\n\nfrom hydra.core.config_store import ConfigStore\n\n@dataclass\nclass MySQLConfig:\n host: str = "localhost"\n port: int = 3306\n\ncs = ConfigStore.instance()\n\n# Using the type\ncs.store(name="config1", node=MySQLConfig)\n# Using an instance, overriding some default values\ncs.store(name="config2", node=MySQLConfig(host="test.db", port=3307))\n# Using a dictionary, forfeiting runtime type safety\ncs.store(name="config3", node={"host": "localhost", "port": 3308})\n')))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/240de8c7.77d7a43c.js b/assets/js/240de8c7.77d7a43c.js deleted file mode 100644 index f89b7121df..0000000000 --- a/assets/js/240de8c7.77d7a43c.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[1132],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>p,MDXProvider:()=>m,mdx:()=>f,useMDXComponents:()=>d,withMDXComponents:()=>c});var o=t(96540);function r(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function a(){return a=Object.assign||function(e){for(var n=1;n=0||(r[t]=e[t]);return r}(e,n);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(o=0;o=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(r[t]=e[t])}return r}var p=o.createContext({}),c=function(e){return function(n){var t=d(n.components);return o.createElement(e,a({},n,{components:t}))}},d=function(e){var n=o.useContext(p),t=n;return e&&(t="function"==typeof e?e(n):s(s({},n),e)),t},m=function(e){var n=d(e.components);return o.createElement(p.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return o.createElement(o.Fragment,{},n)}},g=o.forwardRef((function(e,n){var t=e.components,r=e.mdxType,a=e.originalType,i=e.parentName,p=l(e,["components","mdxType","originalType","parentName"]),c=d(t),m=r,g=c["".concat(i,".").concat(m)]||c[m]||u[m]||a;return t?o.createElement(g,s(s({ref:n},p),{},{components:t})):o.createElement(g,s({ref:n},p))}));function f(e,n){var t=arguments,r=n&&n.mdxType;if("string"==typeof e||r){var a=t.length,i=new Array(a);i[0]=g;var s={};for(var l in n)hasOwnProperty.call(n,l)&&(s[l]=n[l]);s.originalType=e,s.mdxType="string"==typeof e?e:r,i[1]=s;for(var p=2;p{t.r(n),t.d(n,{contentTitle:()=>l,default:()=>m,frontMatter:()=>s,metadata:()=>p,toc:()=>c});var o=t(58168),r=t(98587),a=(t(96540),t(15680)),i=["components"],s={id:"config_store",title:"Config Store API"},l=void 0,p={unversionedId:"tutorials/structured_config/config_store",id:"version-1.3/tutorials/structured_config/config_store",title:"Config Store API",description:"Throughout the rest of tutorials, we will be using ConfigStore to register dataclasses as input configs in Hydra.",source:"@site/versioned_docs/version-1.3/tutorials/structured_config/10_config_store.md",sourceDirName:"tutorials/structured_config",slug:"/tutorials/structured_config/config_store",permalink:"/docs/1.3/tutorials/structured_config/config_store",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/tutorials/structured_config/10_config_store.md",tags:[],version:"1.3",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:10,frontMatter:{id:"config_store",title:"Config Store API"},sidebar:"docs",previous:{title:"Introduction to Structured Configs",permalink:"/docs/1.3/tutorials/structured_config/intro"},next:{title:"Minimal example",permalink:"/docs/1.3/tutorials/structured_config/minimal_example"}},c=[{value:"API",id:"api",children:[],level:3},{value:"ConfigStore and YAML input configs",id:"configstore-and-yaml-input-configs",children:[],level:3},{value:"Example node values",id:"example-node-values",children:[],level:3}],d={toc:c};function m(e){var n=e.components,t=(0,r.A)(e,i);return(0,a.mdx)("wrapper",(0,o.A)({},d,t,{components:n,mdxType:"MDXLayout"}),(0,a.mdx)("p",null,"Throughout the rest of tutorials, we will be using ",(0,a.mdx)("inlineCode",{parentName:"p"},"ConfigStore")," to register dataclasses as input configs in Hydra.\n",(0,a.mdx)("inlineCode",{parentName:"p"},"ConfigStore")," is a singleton storing configs in memory.\nThe primary API for interacting with the ",(0,a.mdx)("inlineCode",{parentName:"p"},"ConfigStore")," is the store method described below."),(0,a.mdx)("h3",{id:"api"},"API"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python"},'class ConfigStore(metaclass=Singleton):\n def store(\n self,\n name: str,\n node: Any,\n group: Optional[str] = None,\n package: Optional[str] = "_group_",\n provider: Optional[str] = None,\n ) -> None:\n """\n Stores a config node into the repository\n :param name: config name\n :param node: config node, can be DictConfig, ListConfig,\n Structured configs and even dict and list\n :param group: config group, subgroup separator is \'/\',\n for example hydra/launcher\n :param package: Config node parent hierarchy.\n Child separator is \'.\', for example foo.bar.baz\n :param provider: the name of the module/app providing this config.\n Helps debugging.\n """\n ...\n')),(0,a.mdx)("h3",{id:"configstore-and-yaml-input-configs"},"ConfigStore and YAML input configs"),(0,a.mdx)("p",null,(0,a.mdx)("inlineCode",{parentName:"p"},"ConfigStore")," has feature parity with YAML input configs. On top of that, it also provides typing validation.\n",(0,a.mdx)("inlineCode",{parentName:"p"},"ConfigStore")," can be used alone or together with YAML. We will see more examples later in this series of tutorials.\nFor now, let's see how the ",(0,a.mdx)("inlineCode",{parentName:"p"},"ConfigStore")," API translates into the YAML input configs, which we've become more familiar\nwith after the basic tutorials."),(0,a.mdx)("p",null,"Say we have a simple application and a ",(0,a.mdx)("inlineCode",{parentName:"p"},"db")," config group with a ",(0,a.mdx)("inlineCode",{parentName:"p"},"mysql")," option:"),(0,a.mdx)("div",{className:"row"},(0,a.mdx)("div",{className:"col col--5"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app.py"',title:'"my_app.py"'},'@hydra.main(version_base=None, config_path="conf")\ndef my_app(cfg: DictConfig) -> None:\n print(OmegaConf.to_yaml(cfg))\n\n\nif __name__ == "__main__":\n my_app()\n'))),(0,a.mdx)("div",{className:"col col--4"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Directory layout"',title:'"Directory','layout"':!0},"\u251c\u2500 conf\n\u2502 \u2514\u2500 db\n\u2502 \u2514\u2500 mysql.yaml\n\u2514\u2500\u2500 my_app.py\n\n\n\n"))),(0,a.mdx)("div",{className:"col col--3"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml"',title:'"db/mysql.yaml"'},"driver: mysql\nuser: omry\npassword: secret\n\n\n\n\n")))),(0,a.mdx)("p",null,"What if we want to add an ",(0,a.mdx)("inlineCode",{parentName:"p"},"postgresql")," option now? Yes, we can easily add a ",(0,a.mdx)("inlineCode",{parentName:"p"},"db/postgresql.yaml")," config group option. But\nthat is not the only way! We can also use ",(0,a.mdx)("inlineCode",{parentName:"p"},"ConfigStore")," to make another config group option for ",(0,a.mdx)("inlineCode",{parentName:"p"},"db")," available to Hydra."),(0,a.mdx)("p",null,"To achieve this, we add a few lines (highlighted) in the above ",(0,a.mdx)("inlineCode",{parentName:"p"},"my_app.py")," file:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app.py" {1-9}',title:'"my_app.py"',"{1-9}":!0},'@dataclass\nclass PostgresSQLConfig:\n driver: str = "postgresql"\n user: str = "jieru"\n password: str = "secret"\n\ncs = ConfigStore.instance()\n# Registering the Config class with the name `postgresql` with the config group `db`\ncs.store(name="postgresql", group="db", node=PostgresSQLConfig)\n\n@hydra.main(version_base=None, config_path="conf")\ndef my_app(cfg: DictConfig) -> None:\n print(OmegaConf.to_yaml(cfg))\n\n\nif __name__ == "__main__":\n my_app()\n')),(0,a.mdx)("p",null,"Now that our application has access to both ",(0,a.mdx)("inlineCode",{parentName:"p"},"db")," config group options, let's run the application to verify:"),(0,a.mdx)("div",{className:"row"},(0,a.mdx)("div",{className:"col col--6"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-commandline",metastring:'title="python my_app.py +db=mysql"',title:'"python',"my_app.py":!0,"+db":'mysql"'},"db:\n driver: mysql\n user: omry\n password: secret\n\n"))),(0,a.mdx)("div",{className:"col col--6"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-commandline",metastring:'title="python my_app.py +db=postgresql"',title:'"python',"my_app.py":!0,"+db":'postgresql"'},"db:\n driver: postgresql\n user: jieru\n password: secret\n\n")))),(0,a.mdx)("h3",{id:"example-node-values"},"Example node values"),(0,a.mdx)("p",null,"A few examples of supported node values parameters:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python"},'from dataclasses import dataclass\n\nfrom hydra.core.config_store import ConfigStore\n\n@dataclass\nclass MySQLConfig:\n host: str = "localhost"\n port: int = 3306\n\ncs = ConfigStore.instance()\n\n# Using the type\ncs.store(name="config1", node=MySQLConfig)\n# Using an instance, overriding some default values\ncs.store(name="config2", node=MySQLConfig(host="test.db", port=3307))\n# Using a dictionary, forfeiting runtime type safety\ncs.store(name="config3", node={"host": "localhost", "port": 3308})\n')))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/25a59092.25db96b7.js b/assets/js/25a59092.25db96b7.js deleted file mode 100644 index 1350528be5..0000000000 --- a/assets/js/25a59092.25db96b7.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[7180],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>s,MDXProvider:()=>u,mdx:()=>h,useMDXComponents:()=>d,withMDXComponents:()=>p});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(){return i=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var s=r.createContext({}),p=function(e){return function(t){var n=d(t.components);return r.createElement(e,i({},t,{components:n}))}},d=function(e){var t=r.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},u=function(e){var t=d(e.components);return r.createElement(s.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},f=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,i=e.originalType,a=e.parentName,s=c(e,["components","mdxType","originalType","parentName"]),p=d(n),u=o,f=p["".concat(a,".").concat(u)]||p[u]||m[u]||i;return n?r.createElement(f,l(l({ref:t},s),{},{components:n})):r.createElement(f,l({ref:t},s))}));function h(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var i=n.length,a=new Array(i);a[0]=f;var l={};for(var c in t)hasOwnProperty.call(t,c)&&(l[c]=t[c]);l.originalType=e,l.mdxType="string"==typeof e?e:o,a[1]=l;for(var s=2;s{n.d(t,{A:()=>o});var r=n(96540);function o(e){var t=(0,r.useRef)(null),n=(0,r.useRef)("undefined"!=typeof document?document.createElement("script"):null);return(0,r.useEffect)((function(){t.current.appendChild(n.current)}),[]),(0,r.useEffect)((function(){for(var t in e)e.hasOwnProperty(t)&&(n.current[t]=e[t])})),r.createElement("div",{ref:t})}},77914:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>s,default:()=>m,frontMatter:()=>c,metadata:()=>p,toc:()=>d});var r=n(58168),o=n(98587),i=(n(96540),n(15680)),a=n(57259),l=["components"],c={id:"tab_completion",title:"Tab completion",sidebar_label:"Tab completion"},s=void 0,p={unversionedId:"tutorials/basic/running_your_app/tab_completion",id:"tutorials/basic/running_your_app/tab_completion",title:"Tab completion",description:"Tab completion can complete config groups, config nodes and values.",source:"@site/docs/tutorials/basic/running_your_app/6_tab_completion.md",sourceDirName:"tutorials/basic/running_your_app",slug:"/tutorials/basic/running_your_app/tab_completion",permalink:"/docs/tutorials/basic/running_your_app/tab_completion",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/tutorials/basic/running_your_app/6_tab_completion.md",tags:[],version:"current",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:6,frontMatter:{id:"tab_completion",title:"Tab completion",sidebar_label:"Tab completion"},sidebar:"docs",previous:{title:"Debugging",permalink:"/docs/tutorials/basic/running_your_app/debugging"},next:{title:"Introduction to Structured Configs",permalink:"/docs/tutorials/structured_config/intro"}},d=[{value:"Install tab completion",id:"install-tab-completion",children:[{value:"Fish instructions",id:"fish-instructions",children:[],level:4},{value:"Zsh instructions",id:"zsh-instructions",children:[],level:4}],level:3}],u={toc:d};function m(e){var t=e.components,n=(0,o.A)(e,l);return(0,i.mdx)("wrapper",(0,r.A)({},u,n,{components:t,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Tab completion can complete config groups, config nodes and values.\nTo complete paths, start them with ",(0,i.mdx)("inlineCode",{parentName:"p"},"/")," or ",(0,i.mdx)("inlineCode",{parentName:"p"},"./"),"."),(0,i.mdx)("p",null,"See this short video demonstration of tab completion:"),(0,i.mdx)(a.A,{id:"asciicast-272604",src:"https://asciinema.org/a/272604.js",async:!0,mdxType:"Script"}),(0,i.mdx)("h3",{id:"install-tab-completion"},"Install tab completion"),(0,i.mdx)("p",null,"Get the exact command to install the completion from ",(0,i.mdx)("inlineCode",{parentName:"p"},"--hydra-help"),".\nCurrently, Bash, zsh and Fish are supported.\nWe are relying on the community to implement tab completion plugins for additional shells."),(0,i.mdx)("h4",{id:"fish-instructions"},"Fish instructions"),(0,i.mdx)("p",null,"Fish support requires version >= 3.1.2.\nPrevious versions will work but add an extra space after ",(0,i.mdx)("inlineCode",{parentName:"p"},"."),"."),(0,i.mdx)("p",null,"Because the fish shell implements special behavior for expanding words prefixed\nwith a tilde character '~', command-line completion does not work for\n",(0,i.mdx)("a",{parentName:"p",href:"/docs/advanced/override_grammar/basic#modifying-the-defaults-list"},"tilde deletions"),"."),(0,i.mdx)("h4",{id:"zsh-instructions"},"Zsh instructions"),(0,i.mdx)("p",null,"Zsh is compatible with the existing Bash shell completion by appending"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre"},"autoload -Uz bashcompinit && bashcompinit\n")),(0,i.mdx)("p",null,"to the ",(0,i.mdx)("inlineCode",{parentName:"p"},".zshrc")," file after ",(0,i.mdx)("inlineCode",{parentName:"p"},"compinit"),", restarting the shell and then using the commands provided for Bash."),(0,i.mdx)("p",null,"Because the zsh shell implements special behavior for expanding words prefixed\nwith a tilde character '~', command-line completion does not work for\n",(0,i.mdx)("a",{parentName:"p",href:"/docs/advanced/override_grammar/basic#modifying-the-defaults-list"},"tilde deletions"),"."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/25a59092.8aca5a02.js b/assets/js/25a59092.8aca5a02.js new file mode 100644 index 0000000000..240d262366 --- /dev/null +++ b/assets/js/25a59092.8aca5a02.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[7180],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>c,MDXProvider:()=>u,mdx:()=>h,useMDXComponents:()=>d,withMDXComponents:()=>p});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(){return i=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var c=r.createContext({}),p=function(e){return function(t){var n=d(t.components);return r.createElement(e,i({},t,{components:n}))}},d=function(e){var t=r.useContext(c),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},u=function(e){var t=d(e.components);return r.createElement(c.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},f=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,i=e.originalType,a=e.parentName,c=s(e,["components","mdxType","originalType","parentName"]),p=d(n),u=o,f=p["".concat(a,".").concat(u)]||p[u]||m[u]||i;return n?r.createElement(f,l(l({ref:t},c),{},{components:n})):r.createElement(f,l({ref:t},c))}));function h(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var i=n.length,a=new Array(i);a[0]=f;var l={};for(var s in t)hasOwnProperty.call(t,s)&&(l[s]=t[s]);l.originalType=e,l.mdxType="string"==typeof e?e:o,a[1]=l;for(var c=2;c{n.d(t,{A:()=>o});var r=n(96540);function o(e){var t=(0,r.useRef)(null),n=(0,r.useRef)("undefined"!=typeof document?document.createElement("script"):null);return(0,r.useEffect)((function(){t.current.appendChild(n.current)}),[]),(0,r.useEffect)((function(){for(var t in e)e.hasOwnProperty(t)&&(n.current[t]=e[t])})),r.createElement("div",{ref:t})}},77914:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>c,default:()=>m,frontMatter:()=>s,metadata:()=>p,toc:()=>d});var r=n(58168),o=n(98587),i=(n(96540),n(15680)),a=n(57259),l=["components"],s={id:"tab_completion",title:"Tab completion",sidebar_label:"Tab completion"},c=void 0,p={unversionedId:"tutorials/basic/running_your_app/tab_completion",id:"tutorials/basic/running_your_app/tab_completion",title:"Tab completion",description:"Tab completion can complete config groups, config nodes and values.",source:"@site/docs/tutorials/basic/running_your_app/6_tab_completion.md",sourceDirName:"tutorials/basic/running_your_app",slug:"/tutorials/basic/running_your_app/tab_completion",permalink:"/docs/tutorials/basic/running_your_app/tab_completion",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/tutorials/basic/running_your_app/6_tab_completion.md",tags:[],version:"current",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:6,frontMatter:{id:"tab_completion",title:"Tab completion",sidebar_label:"Tab completion"},sidebar:"docs",previous:{title:"Debugging",permalink:"/docs/tutorials/basic/running_your_app/debugging"},next:{title:"Introduction to Structured Configs",permalink:"/docs/tutorials/structured_config/intro"}},d=[{value:"Install tab completion",id:"install-tab-completion",children:[{value:"Fish instructions",id:"fish-instructions",children:[],level:4},{value:"Zsh instructions",id:"zsh-instructions",children:[],level:4}],level:3}],u={toc:d};function m(e){var t=e.components,n=(0,o.A)(e,l);return(0,i.mdx)("wrapper",(0,r.A)({},u,n,{components:t,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Tab completion can complete config groups, config nodes and values.\nTo complete paths, start them with ",(0,i.mdx)("inlineCode",{parentName:"p"},"/")," or ",(0,i.mdx)("inlineCode",{parentName:"p"},"./"),"."),(0,i.mdx)("p",null,"See this short video demonstration of tab completion:"),(0,i.mdx)(a.A,{id:"asciicast-272604",src:"https://asciinema.org/a/272604.js",async:!0,mdxType:"Script"}),(0,i.mdx)("h3",{id:"install-tab-completion"},"Install tab completion"),(0,i.mdx)("p",null,"Get the exact command to install the completion from ",(0,i.mdx)("inlineCode",{parentName:"p"},"--hydra-help"),".\nCurrently, Bash, zsh and Fish are supported.\nWe are relying on the community to implement tab completion plugins for additional shells."),(0,i.mdx)("h4",{id:"fish-instructions"},"Fish instructions"),(0,i.mdx)("p",null,"Fish support requires version >= 3.1.2.\nPrevious versions will work but add an extra space after ",(0,i.mdx)("inlineCode",{parentName:"p"},"."),"."),(0,i.mdx)("p",null,"Because the fish shell implements special behavior for expanding words prefixed\nwith a tilde character '~', command-line completion does not work for\n",(0,i.mdx)("a",{parentName:"p",href:"/docs/advanced/override_grammar/basic#modifying-the-defaults-list"},"tilde deletions"),"."),(0,i.mdx)("h4",{id:"zsh-instructions"},"Zsh instructions"),(0,i.mdx)("p",null,"Zsh is compatible with the existing Bash shell completion by appending"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre"},"autoload -Uz bashcompinit && bashcompinit\n")),(0,i.mdx)("p",null,"to the ",(0,i.mdx)("inlineCode",{parentName:"p"},".zshrc")," file after ",(0,i.mdx)("inlineCode",{parentName:"p"},"compinit"),", restarting the shell and then using the commands provided for Bash."),(0,i.mdx)("p",null,"Because the zsh shell implements special behavior for expanding words prefixed\nwith a tilde character '~', command-line completion does not work for\n",(0,i.mdx)("a",{parentName:"p",href:"/docs/advanced/override_grammar/basic#modifying-the-defaults-list"},"tilde deletions"),"."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2682ecde.5c538e37.js b/assets/js/2682ecde.5c538e37.js new file mode 100644 index 0000000000..e206db65f3 --- /dev/null +++ b/assets/js/2682ecde.5c538e37.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[160],{15680:(e,n,r)=>{r.r(n),r.d(n,{MDXContext:()=>s,MDXProvider:()=>c,mdx:()=>g,useMDXComponents:()=>u,withMDXComponents:()=>d});var t=r(96540);function a(e,n,r){return n in e?Object.defineProperty(e,n,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[n]=r,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(a[r]=e[r]);return a}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(a[r]=e[r])}return a}var s=t.createContext({}),d=function(e){return function(n){var r=u(n.components);return t.createElement(e,i({},n,{components:r}))}},u=function(e){var n=t.useContext(s),r=n;return e&&(r="function"==typeof e?e(n):o(o({},n),e)),r},c=function(e){var n=u(e.components);return t.createElement(s.Provider,{value:n},e.children)},m={inlineCode:"code",wrapper:function(e){var n=e.children;return t.createElement(t.Fragment,{},n)}},h=t.forwardRef((function(e,n){var r=e.components,a=e.mdxType,i=e.originalType,l=e.parentName,s=p(e,["components","mdxType","originalType","parentName"]),d=u(r),c=a,h=d["".concat(l,".").concat(c)]||d[c]||m[c]||i;return r?t.createElement(h,o(o({ref:n},s),{},{components:r})):t.createElement(h,o({ref:n},s))}));function g(e,n){var r=arguments,a=n&&n.mdxType;if("string"==typeof e||a){var i=r.length,l=new Array(i);l[0]=h;var o={};for(var p in n)hasOwnProperty.call(n,p)&&(o[p]=n[p]);o.originalType=e,o.mdxType="string"==typeof e?e:a,l[1]=o;for(var s=2;s{r.d(n,{A:()=>p,C:()=>s});var t=r(58168),a=r(96540),i=r(75489),l=r(44586),o=r(74098);function p(e){return a.createElement(i.default,(0,t.A)({},e,{to:(n=e.to,p=(0,o.useActiveVersion)(),(0,l.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(r=null==p?void 0:p.name)?r:"current"]+n),target:"_blank"}));var n,r,p}function s(e){var n,r=null!=(n=e.text)?n:"Example (Click Here)";return a.createElement(p,e,a.createElement("span",null,"\xa0"),a.createElement("img",{src:"https://img.shields.io/badge/-"+r+"-informational",alt:"Example (Click Here)"}))}},4275:(e,n,r)=>{r.r(n),r.d(n,{contentTitle:()=>s,default:()=>m,frontMatter:()=>p,metadata:()=>d,toc:()=>u});var t=r(58168),a=r(98587),i=(r(96540),r(15680)),l=r(49595),o=["components"],p={id:"rq_launcher",title:"RQ Launcher plugin",sidebar_label:"RQ Launcher plugin"},s=void 0,d={unversionedId:"plugins/rq_launcher",id:"plugins/rq_launcher",title:"RQ Launcher plugin",description:"PyPI",source:"@site/docs/plugins/rq_launcher.md",sourceDirName:"plugins",slug:"/plugins/rq_launcher",permalink:"/docs/plugins/rq_launcher",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/plugins/rq_launcher.md",tags:[],version:"current",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"rq_launcher",title:"RQ Launcher plugin",sidebar_label:"RQ Launcher plugin"},sidebar:"docs",previous:{title:"Ray Launcher plugin",permalink:"/docs/plugins/ray_launcher"},next:{title:"Submitit Launcher plugin",permalink:"/docs/plugins/submitit_launcher"}},u=[{value:"Installation",id:"installation",children:[],level:3},{value:"Usage",id:"usage",children:[],level:3}],c={toc:u};function m(e){var n=e.components,r=(0,a.A)(e,o);return(0,i.mdx)("wrapper",(0,t.A)({},c,r,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,(0,i.mdx)("a",{parentName:"p",href:"https://pypi.org/project/hydra-rq-launcher/"},(0,i.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/v/hydra-rq-launcher",alt:"PyPI"})),"\n",(0,i.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/l/hydra-rq-launcher",alt:"PyPI - License"}),"\n",(0,i.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/pyversions/hydra-rq-launcher",alt:"PyPI - Python Version"}),"\n",(0,i.mdx)("a",{parentName:"p",href:"https://pypistats.org/packages/hydra-rq-launcher"},(0,i.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/dm/hydra-rq-launcher.svg",alt:"PyPI - Downloads"})),(0,i.mdx)(l.C,{text:"Example application",to:"plugins/hydra_rq_launcher/examples",mdxType:"ExampleGithubLink"}),(0,i.mdx)(l.C,{text:"Plugin source",to:"plugins/hydra_rq_launcher",mdxType:"ExampleGithubLink"})),(0,i.mdx)("p",null,"The RQ Launcher plugin provides a launcher for distributed execution and job queuing based on ",(0,i.mdx)("a",{parentName:"p",href:"https://python-rq.org"},"Redis Queue (RQ)"),"."),(0,i.mdx)("p",null,"RQ launcher allows parallelizing across multiple nodes and scheduling jobs in queues. Usage of this plugin requires a ",(0,i.mdx)("a",{parentName:"p",href:"https://redis.io/topics/quickstart"},"Redis server"),". When parallelisation on a single node is intended, the Joblib launcher may be preferable, since it works without a database."),(0,i.mdx)("h3",{id:"installation"},"Installation"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"pip install hydra-rq-launcher --upgrade\n")),(0,i.mdx)("p",null,"Usage of this plugin requires a ",(0,i.mdx)("a",{parentName:"p",href:"https://redis.io/topics/quickstart"},"Redis server"),"."),(0,i.mdx)("p",null,"Note that RQ does ",(0,i.mdx)("a",{parentName:"p",href:"https://python-rq.org/docs/#limitations"},"not support Windows"),"."),(0,i.mdx)("h3",{id:"usage"},"Usage"),(0,i.mdx)("p",null,"Once installed, add ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra/launcher=rq")," to your command line. Alternatively, override ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra/launcher")," in your config:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - override hydra/launcher: rq\n")),(0,i.mdx)("p",null,"The default configuration is as follows:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python your_app.py hydra/launcher=rq --cfg hydra -p hydra.launcher"',title:'"$',python:!0,"your_app.py":!0,"hydra/launcher":"rq","--cfg":!0,hydra:!0,"-p":!0,'hydra.launcher"':!0},"# @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")),(0,i.mdx)("p",null,"Further descriptions on the variables can be found in the plugin config file, defined ",(0,i.mdx)(l.A,{to:"plugins/hydra_rq_launcher/hydra_plugins/hydra_rq_launcher/config.py",mdxType:"GithubLink"},"here"),". There are several standard approaches for configuring plugins. Check ",(0,i.mdx)("a",{parentName:"p",href:"/docs/patterns/configuring_plugins"},"this page")," for more information."),(0,i.mdx)("p",null,"The plugin is using environment variables to store Redis connection information. The environment variables ",(0,i.mdx)("inlineCode",{parentName:"p"},"REDIS_HOST"),", ",(0,i.mdx)("inlineCode",{parentName:"p"},"REDIS_PORT"),", ",(0,i.mdx)("inlineCode",{parentName:"p"},"REDIS_DB"),", and ",(0,i.mdx)("inlineCode",{parentName:"p"},"REDIS_PASSWORD"),", are used for the host address, port, database, and password of the server, respectively. Support for Redis SSL connections is controlled through ",(0,i.mdx)("inlineCode",{parentName:"p"},"REDIS_SSL")," and ",(0,i.mdx)("inlineCode",{parentName:"p"},"REDIS_SSL_CA_CERTS"),"; see ",(0,i.mdx)("a",{parentName:"p",href:"https://github.com/andymccurdy/redis-py#ssl-connections"},"redis-py")," documentation."),(0,i.mdx)("p",null,"For example, they might be set as follows when using ",(0,i.mdx)("inlineCode",{parentName:"p"},"bash")," or ",(0,i.mdx)("inlineCode",{parentName:"p"},"zsh")," as a shell:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},'export REDIS_HOST="localhost"\nexport REDIS_PORT="6379"\nexport REDIS_DB="0"\nexport REDIS_PASSWORD=""\n')),(0,i.mdx)("p",null,"Enable SSL by setting the relevant environment variables. e.g:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"export REDIS_SSL=true\nexport REDIS_SSL_CA_CERTS=/etc/ssl/certs/ca-certificates.crt\n")),(0,i.mdx)("p",null,"Assuming configured environment variables, workers connecting to the Redis server can be launched using:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"rq worker --url redis://:$REDIS_PASSWORD@$REDIS_HOST:$REDIS_PORT/$REDIS_DB\n")),(0,i.mdx)("p",null,"An ",(0,i.mdx)(l.A,{to:"plugins/hydra_rq_launcher/example",mdxType:"GithubLink"},"example application")," using this launcher is provided in the plugin repository."),(0,i.mdx)("p",null,"Starting the app with ",(0,i.mdx)("inlineCode",{parentName:"p"},"python my_app.py --multirun task=1,2,3,4,5")," will enqueue five jobs to be processed by worker instances:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text"},"$ 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] #1 : task=1\n[HYDRA] Enqueued 00c6a32d-e5a4-432c-a0f3-b9d4ef0dd585\n[HYDRA] #2 : task=2\n[HYDRA] Enqueued 63b90f27-0711-4c95-8f63-70164fd850df\n[HYDRA] #3 : task=3\n[HYDRA] Enqueued b1d49825-8b28-4516-90ca-8106477e1eb1\n[HYDRA] #4 : task=4\n[HYDRA] Enqueued ed96bdaa-087d-4c7f-9ecb-56daf948d5e2\n[HYDRA] #5 : task=5\n[HYDRA] Finished enqueuing\n[HYDRA] Polling job statuses every 1.0 sec\n")),(0,i.mdx)("p",null,"Note that any dependencies need to be installed in the Python environment used to run the RQ worker. For serialization of jobs ",(0,i.mdx)("a",{parentName:"p",href:"https://github.com/cloudpickle/cloudpickle"},(0,i.mdx)("inlineCode",{parentName:"a"},"cloudpickle"))," is used."),(0,i.mdx)("p",null,"The ",(0,i.mdx)("a",{parentName:"p",href:"https://python-rq.org/"},"RQ documentation")," holds further information on ",(0,i.mdx)("a",{parentName:"p",href:"http://python-rq.org/docs/monitoring/"},"job monitoring"),", which can be done via console or ",(0,i.mdx)("a",{parentName:"p",href:"https://github.com/nvie/rq-dashboard"},"web interfaces"),", and provides ",(0,i.mdx)("a",{parentName:"p",href:"https://python-rq.org/patterns/"},"patterns")," for worker and exception handling."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2682ecde.621be004.js b/assets/js/2682ecde.621be004.js deleted file mode 100644 index b87c809605..0000000000 --- a/assets/js/2682ecde.621be004.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[160],{15680:(e,n,r)=>{r.r(n),r.d(n,{MDXContext:()=>s,MDXProvider:()=>c,mdx:()=>g,useMDXComponents:()=>d,withMDXComponents:()=>u});var t=r(96540);function a(e,n,r){return n in e?Object.defineProperty(e,n,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[n]=r,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(a[r]=e[r]);return a}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(a[r]=e[r])}return a}var s=t.createContext({}),u=function(e){return function(n){var r=d(n.components);return t.createElement(e,i({},n,{components:r}))}},d=function(e){var n=t.useContext(s),r=n;return e&&(r="function"==typeof e?e(n):o(o({},n),e)),r},c=function(e){var n=d(e.components);return t.createElement(s.Provider,{value:n},e.children)},m={inlineCode:"code",wrapper:function(e){var n=e.children;return t.createElement(t.Fragment,{},n)}},h=t.forwardRef((function(e,n){var r=e.components,a=e.mdxType,i=e.originalType,l=e.parentName,s=p(e,["components","mdxType","originalType","parentName"]),u=d(r),c=a,h=u["".concat(l,".").concat(c)]||u[c]||m[c]||i;return r?t.createElement(h,o(o({ref:n},s),{},{components:r})):t.createElement(h,o({ref:n},s))}));function g(e,n){var r=arguments,a=n&&n.mdxType;if("string"==typeof e||a){var i=r.length,l=new Array(i);l[0]=h;var o={};for(var p in n)hasOwnProperty.call(n,p)&&(o[p]=n[p]);o.originalType=e,o.mdxType="string"==typeof e?e:a,l[1]=o;for(var s=2;s{r.d(n,{A:()=>p,C:()=>s});var t=r(58168),a=r(96540),i=r(75489),l=r(44586),o=r(74098);function p(e){return a.createElement(i.default,(0,t.A)({},e,{to:(n=e.to,p=(0,o.useActiveVersion)(),(0,l.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(r=null==p?void 0:p.name)?r:"current"]+n),target:"_blank"}));var n,r,p}function s(e){var n,r=null!=(n=e.text)?n:"Example (Click Here)";return a.createElement(p,e,a.createElement("span",null,"\xa0"),a.createElement("img",{src:"https://img.shields.io/badge/-"+r+"-informational",alt:"Example (Click Here)"}))}},4275:(e,n,r)=>{r.r(n),r.d(n,{contentTitle:()=>s,default:()=>m,frontMatter:()=>p,metadata:()=>u,toc:()=>d});var t=r(58168),a=r(98587),i=(r(96540),r(15680)),l=r(49595),o=["components"],p={id:"rq_launcher",title:"RQ Launcher plugin",sidebar_label:"RQ Launcher plugin"},s=void 0,u={unversionedId:"plugins/rq_launcher",id:"plugins/rq_launcher",title:"RQ Launcher plugin",description:"PyPI",source:"@site/docs/plugins/rq_launcher.md",sourceDirName:"plugins",slug:"/plugins/rq_launcher",permalink:"/docs/plugins/rq_launcher",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/plugins/rq_launcher.md",tags:[],version:"current",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"rq_launcher",title:"RQ Launcher plugin",sidebar_label:"RQ Launcher plugin"},sidebar:"docs",previous:{title:"Ray Launcher plugin",permalink:"/docs/plugins/ray_launcher"},next:{title:"Submitit Launcher plugin",permalink:"/docs/plugins/submitit_launcher"}},d=[{value:"Installation",id:"installation",children:[],level:3},{value:"Usage",id:"usage",children:[],level:3}],c={toc:d};function m(e){var n=e.components,r=(0,a.A)(e,o);return(0,i.mdx)("wrapper",(0,t.A)({},c,r,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,(0,i.mdx)("a",{parentName:"p",href:"https://pypi.org/project/hydra-rq-launcher/"},(0,i.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/v/hydra-rq-launcher",alt:"PyPI"})),"\n",(0,i.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/l/hydra-rq-launcher",alt:"PyPI - License"}),"\n",(0,i.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/pyversions/hydra-rq-launcher",alt:"PyPI - Python Version"}),"\n",(0,i.mdx)("a",{parentName:"p",href:"https://pypistats.org/packages/hydra-rq-launcher"},(0,i.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/dm/hydra-rq-launcher.svg",alt:"PyPI - Downloads"})),(0,i.mdx)(l.C,{text:"Example application",to:"plugins/hydra_rq_launcher/examples",mdxType:"ExampleGithubLink"}),(0,i.mdx)(l.C,{text:"Plugin source",to:"plugins/hydra_rq_launcher",mdxType:"ExampleGithubLink"})),(0,i.mdx)("p",null,"The RQ Launcher plugin provides a launcher for distributed execution and job queuing based on ",(0,i.mdx)("a",{parentName:"p",href:"https://python-rq.org"},"Redis Queue (RQ)"),"."),(0,i.mdx)("p",null,"RQ launcher allows parallelizing across multiple nodes and scheduling jobs in queues. Usage of this plugin requires a ",(0,i.mdx)("a",{parentName:"p",href:"https://redis.io/topics/quickstart"},"Redis server"),". When parallelisation on a single node is intended, the Joblib launcher may be preferable, since it works without a database."),(0,i.mdx)("h3",{id:"installation"},"Installation"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"pip install hydra-rq-launcher --upgrade\n")),(0,i.mdx)("p",null,"Usage of this plugin requires a ",(0,i.mdx)("a",{parentName:"p",href:"https://redis.io/topics/quickstart"},"Redis server"),"."),(0,i.mdx)("p",null,"Note that RQ does ",(0,i.mdx)("a",{parentName:"p",href:"https://python-rq.org/docs/#limitations"},"not support Windows"),"."),(0,i.mdx)("h3",{id:"usage"},"Usage"),(0,i.mdx)("p",null,"Once installed, add ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra/launcher=rq")," to your command line. Alternatively, override ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra/launcher")," in your config:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - override hydra/launcher: rq\n")),(0,i.mdx)("p",null,"The default configuration is as follows:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python your_app.py hydra/launcher=rq --cfg hydra -p hydra.launcher"',title:'"$',python:!0,"your_app.py":!0,"hydra/launcher":"rq","--cfg":!0,hydra:!0,"-p":!0,'hydra.launcher"':!0},"# @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")),(0,i.mdx)("p",null,"Further descriptions on the variables can be found in the plugin config file, defined ",(0,i.mdx)(l.A,{to:"plugins/hydra_rq_launcher/hydra_plugins/hydra_rq_launcher/config.py",mdxType:"GithubLink"},"here"),". There are several standard approaches for configuring plugins. Check ",(0,i.mdx)("a",{parentName:"p",href:"/docs/patterns/configuring_plugins"},"this page")," for more information."),(0,i.mdx)("p",null,"The plugin is using environment variables to store Redis connection information. The environment variables ",(0,i.mdx)("inlineCode",{parentName:"p"},"REDIS_HOST"),", ",(0,i.mdx)("inlineCode",{parentName:"p"},"REDIS_PORT"),", ",(0,i.mdx)("inlineCode",{parentName:"p"},"REDIS_DB"),", and ",(0,i.mdx)("inlineCode",{parentName:"p"},"REDIS_PASSWORD"),", are used for the host address, port, database, and password of the server, respectively. Support for Redis SSL connections is controlled through ",(0,i.mdx)("inlineCode",{parentName:"p"},"REDIS_SSL")," and ",(0,i.mdx)("inlineCode",{parentName:"p"},"REDIS_SSL_CA_CERTS"),"; see ",(0,i.mdx)("a",{parentName:"p",href:"https://github.com/andymccurdy/redis-py#ssl-connections"},"redis-py")," documentation."),(0,i.mdx)("p",null,"For example, they might be set as follows when using ",(0,i.mdx)("inlineCode",{parentName:"p"},"bash")," or ",(0,i.mdx)("inlineCode",{parentName:"p"},"zsh")," as a shell:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},'export REDIS_HOST="localhost"\nexport REDIS_PORT="6379"\nexport REDIS_DB="0"\nexport REDIS_PASSWORD=""\n')),(0,i.mdx)("p",null,"Enable SSL by setting the relevant environment variables. e.g:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"export REDIS_SSL=true\nexport REDIS_SSL_CA_CERTS=/etc/ssl/certs/ca-certificates.crt\n")),(0,i.mdx)("p",null,"Assuming configured environment variables, workers connecting to the Redis server can be launched using:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"rq worker --url redis://:$REDIS_PASSWORD@$REDIS_HOST:$REDIS_PORT/$REDIS_DB\n")),(0,i.mdx)("p",null,"An ",(0,i.mdx)(l.A,{to:"plugins/hydra_rq_launcher/example",mdxType:"GithubLink"},"example application")," using this launcher is provided in the plugin repository."),(0,i.mdx)("p",null,"Starting the app with ",(0,i.mdx)("inlineCode",{parentName:"p"},"python my_app.py --multirun task=1,2,3,4,5")," will enqueue five jobs to be processed by worker instances:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text"},"$ 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] #1 : task=1\n[HYDRA] Enqueued 00c6a32d-e5a4-432c-a0f3-b9d4ef0dd585\n[HYDRA] #2 : task=2\n[HYDRA] Enqueued 63b90f27-0711-4c95-8f63-70164fd850df\n[HYDRA] #3 : task=3\n[HYDRA] Enqueued b1d49825-8b28-4516-90ca-8106477e1eb1\n[HYDRA] #4 : task=4\n[HYDRA] Enqueued ed96bdaa-087d-4c7f-9ecb-56daf948d5e2\n[HYDRA] #5 : task=5\n[HYDRA] Finished enqueuing\n[HYDRA] Polling job statuses every 1.0 sec\n")),(0,i.mdx)("p",null,"Note that any dependencies need to be installed in the Python environment used to run the RQ worker. For serialization of jobs ",(0,i.mdx)("a",{parentName:"p",href:"https://github.com/cloudpickle/cloudpickle"},(0,i.mdx)("inlineCode",{parentName:"a"},"cloudpickle"))," is used."),(0,i.mdx)("p",null,"The ",(0,i.mdx)("a",{parentName:"p",href:"https://python-rq.org/"},"RQ documentation")," holds further information on ",(0,i.mdx)("a",{parentName:"p",href:"http://python-rq.org/docs/monitoring/"},"job monitoring"),", which can be done via console or ",(0,i.mdx)("a",{parentName:"p",href:"https://github.com/nvie/rq-dashboard"},"web interfaces"),", and provides ",(0,i.mdx)("a",{parentName:"p",href:"https://python-rq.org/patterns/"},"patterns")," for worker and exception handling."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/27546d3e.1bb2c723.js b/assets/js/27546d3e.1bb2c723.js new file mode 100644 index 0000000000..08a27d3d5f --- /dev/null +++ b/assets/js/27546d3e.1bb2c723.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[351],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>s,MDXProvider:()=>m,mdx:()=>f,useMDXComponents:()=>c,withMDXComponents:()=>p});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(){return i=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var s=r.createContext({}),p=function(e){return function(t){var n=c(t.components);return r.createElement(e,i({},t,{components:n}))}},c=function(e){var t=r.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):a(a({},t),e)),n},m=function(e){var t=c(e.components);return r.createElement(s.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},y=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,i=e.originalType,l=e.parentName,s=d(e,["components","mdxType","originalType","parentName"]),p=c(n),m=o,y=p["".concat(l,".").concat(m)]||p[m]||u[m]||i;return n?r.createElement(y,a(a({ref:t},s),{},{components:n})):r.createElement(y,a({ref:t},s))}));function f(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var i=n.length,l=new Array(i);l[0]=y;var a={};for(var d in t)hasOwnProperty.call(t,d)&&(a[d]=t[d]);a.originalType=e,a.mdxType="string"==typeof e?e:o,l[1]=a;for(var s=2;s{n.r(t),n.d(t,{contentTitle:()=>d,default:()=>m,frontMatter:()=>a,metadata:()=>s,toc:()=>p});var r=n(58168),o=n(98587),i=(n(96540),n(15680)),l=["components"],a={id:"style_guide",title:"Style Guide",sidebar_label:"Style Guide"},d=void 0,s={unversionedId:"development/style_guide",id:"version-1.1/development/style_guide",title:"Style Guide",description:"The code need to pass verification by the following tools:",source:"@site/versioned_docs/version-1.1/development/style_guide.md",sourceDirName:"development",slug:"/development/style_guide",permalink:"/docs/1.1/development/style_guide",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/development/style_guide.md",tags:[],version:"1.1",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"style_guide",title:"Style Guide",sidebar_label:"Style Guide"},sidebar:"version-1.1/docs",previous:{title:"Testing",permalink:"/docs/1.1/development/testing"},next:{title:"Documentation",permalink:"/docs/1.1/development/documentation"}},p=[],c={toc:p};function m(e){var t=e.components,n=(0,o.A)(e,l);return(0,i.mdx)("wrapper",(0,r.A)({},c,n,{components:t,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"The code need to pass verification by the following tools:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"black .")," : Automatic code formatting for Python"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"flake8")," : PEP8 compliance checker for Python, this includes copyright header verification"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"isort .")," : Ensure imports are sorted properly"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"mypy --strict .")," : Ensures code passes strict type checking"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"yamllint .")," : Ensures that yaml files are syntactically correct and properly indented.")),(0,i.mdx)("p",null,"The easiest way to run the required verifications is: "),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"nox -s lint")," : for the Hydra core"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"nox -s lint_plugins")," : for the included plugins")),(0,i.mdx)("p",null,"isort is a bit tricky to run for plugins. the best way to get it to sort the plugins imports is with the FIX environment\nvariable:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre"},"$ FIX=1 nox -s lint_plugins\n")),(0,i.mdx)("p",null,"It is also recommended that you install pre-commit hooks (use ",(0,i.mdx)("inlineCode",{parentName:"p"},"pre-commit install"),").\npre-commit will execute some of the above tests when you commit your code locally.\nYou can disable it by appending ",(0,i.mdx)("inlineCode",{parentName:"p"},"-n")," to your commit command: ",(0,i.mdx)("inlineCode",{parentName:"p"},"git commit -m wip -n")),(0,i.mdx)("p",null,"Pull requests that do not lint will fail the automated testing."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/27546d3e.f9f8c256.js b/assets/js/27546d3e.f9f8c256.js deleted file mode 100644 index 58e1a164aa..0000000000 --- a/assets/js/27546d3e.f9f8c256.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[351],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>s,MDXProvider:()=>m,mdx:()=>f,useMDXComponents:()=>c,withMDXComponents:()=>p});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(){return i=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var s=r.createContext({}),p=function(e){return function(t){var n=c(t.components);return r.createElement(e,i({},t,{components:n}))}},c=function(e){var t=r.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):a(a({},t),e)),n},m=function(e){var t=c(e.components);return r.createElement(s.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},y=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,i=e.originalType,l=e.parentName,s=d(e,["components","mdxType","originalType","parentName"]),p=c(n),m=o,y=p["".concat(l,".").concat(m)]||p[m]||u[m]||i;return n?r.createElement(y,a(a({ref:t},s),{},{components:n})):r.createElement(y,a({ref:t},s))}));function f(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var i=n.length,l=new Array(i);l[0]=y;var a={};for(var d in t)hasOwnProperty.call(t,d)&&(a[d]=t[d]);a.originalType=e,a.mdxType="string"==typeof e?e:o,l[1]=a;for(var s=2;s{n.r(t),n.d(t,{contentTitle:()=>d,default:()=>m,frontMatter:()=>a,metadata:()=>s,toc:()=>p});var r=n(58168),o=n(98587),i=(n(96540),n(15680)),l=["components"],a={id:"style_guide",title:"Style Guide",sidebar_label:"Style Guide"},d=void 0,s={unversionedId:"development/style_guide",id:"version-1.1/development/style_guide",title:"Style Guide",description:"The code need to pass verification by the following tools:",source:"@site/versioned_docs/version-1.1/development/style_guide.md",sourceDirName:"development",slug:"/development/style_guide",permalink:"/docs/1.1/development/style_guide",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/development/style_guide.md",tags:[],version:"1.1",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"style_guide",title:"Style Guide",sidebar_label:"Style Guide"},sidebar:"version-1.1/docs",previous:{title:"Testing",permalink:"/docs/1.1/development/testing"},next:{title:"Documentation",permalink:"/docs/1.1/development/documentation"}},p=[],c={toc:p};function m(e){var t=e.components,n=(0,o.A)(e,l);return(0,i.mdx)("wrapper",(0,r.A)({},c,n,{components:t,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"The code need to pass verification by the following tools:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"black .")," : Automatic code formatting for Python"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"flake8")," : PEP8 compliance checker for Python, this includes copyright header verification"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"isort .")," : Ensure imports are sorted properly"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"mypy --strict .")," : Ensures code passes strict type checking"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"yamllint .")," : Ensures that yaml files are syntactically correct and properly indented.")),(0,i.mdx)("p",null,"The easiest way to run the required verifications is: "),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"nox -s lint")," : for the Hydra core"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"nox -s lint_plugins")," : for the included plugins")),(0,i.mdx)("p",null,"isort is a bit tricky to run for plugins. the best way to get it to sort the plugins imports is with the FIX environment\nvariable:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre"},"$ FIX=1 nox -s lint_plugins\n")),(0,i.mdx)("p",null,"It is also recommended that you install pre-commit hooks (use ",(0,i.mdx)("inlineCode",{parentName:"p"},"pre-commit install"),").\npre-commit will execute some of the above tests when you commit your code locally.\nYou can disable it by appending ",(0,i.mdx)("inlineCode",{parentName:"p"},"-n")," to your commit command: ",(0,i.mdx)("inlineCode",{parentName:"p"},"git commit -m wip -n")),(0,i.mdx)("p",null,"Pull requests that do not lint will fail the automated testing."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/27af8fe6.721eb416.js b/assets/js/27af8fe6.721eb416.js deleted file mode 100644 index a0892b058c..0000000000 --- a/assets/js/27af8fe6.721eb416.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[4312],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>s,MDXProvider:()=>d,mdx:()=>y,useMDXComponents:()=>c,withMDXComponents:()=>m});var a=n(96540);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(){return i=Object.assign||function(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var s=a.createContext({}),m=function(e){return function(t){var n=c(t.components);return a.createElement(e,i({},t,{components:n}))}},c=function(e){var t=a.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},d=function(e){var t=c(e.components);return a.createElement(s.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},f=a.forwardRef((function(e,t){var n=e.components,r=e.mdxType,i=e.originalType,o=e.parentName,s=p(e,["components","mdxType","originalType","parentName"]),m=c(n),d=r,f=m["".concat(o,".").concat(d)]||m[d]||u[d]||i;return n?a.createElement(f,l(l({ref:t},s),{},{components:n})):a.createElement(f,l({ref:t},s))}));function y(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var i=n.length,o=new Array(i);o[0]=f;var l={};for(var p in t)hasOwnProperty.call(t,p)&&(l[p]=t[p]);l.originalType=e,l.mdxType="string"==typeof e?e:r,o[1]=l;for(var s=2;s{n.d(t,{A:()=>p,C:()=>s});var a=n(58168),r=n(96540),i=n(75489),o=n(44586),l=n(74098);function p(e){return r.createElement(i.default,(0,a.A)({},e,{to:(t=e.to,p=(0,l.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==p?void 0:p.name)?n:"current"]+t),target:"_blank"}));var t,n,p}function s(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return r.createElement(p,e,r.createElement("span",null,"\xa0"),r.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},40147:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>s,default:()=>u,frontMatter:()=>p,metadata:()=>m,toc:()=>c});var a=n(58168),r=n(98587),i=(n(96540),n(15680)),o=n(49595),l=["components"],p={id:"simple_cli",title:"A simple command-line application"},s=void 0,m={unversionedId:"tutorials/basic/your_first_app/simple_cli",id:"tutorials/basic/your_first_app/simple_cli",title:"A simple command-line application",description:"This is a simple Hydra application that prints your configuration.",source:"@site/docs/tutorials/basic/your_first_app/1_simple_cli.md",sourceDirName:"tutorials/basic/your_first_app",slug:"/tutorials/basic/your_first_app/simple_cli",permalink:"/docs/tutorials/basic/your_first_app/simple_cli",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/tutorials/basic/your_first_app/1_simple_cli.md",tags:[],version:"current",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:1,frontMatter:{id:"simple_cli",title:"A simple command-line application"},sidebar:"docs",previous:{title:"Tutorials intro",permalink:"/docs/tutorials/intro"},next:{title:"Specifying a config file",permalink:"/docs/tutorials/basic/your_first_app/config_file"}},c=[],d={toc:c};function u(e){var t=e.components,n=(0,r.A)(e,l);return(0,i.mdx)("wrapper",(0,a.A)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,i.mdx)(o.C,{to:"examples/tutorials/basic/your_first_hydra_app/1_simple_cli/my_app.py",mdxType:"ExampleGithubLink"}),(0,i.mdx)("p",null,"This is a simple Hydra application that prints your configuration.\nThe ",(0,i.mdx)("inlineCode",{parentName:"p"},"my_app")," function is a placeholder for your code.\nWe will slowly evolve this example to showcase more Hydra features."),(0,i.mdx)("p",null,"The examples in this tutorial are available ",(0,i.mdx)(o.A,{to:"examples/tutorials/basic",mdxType:"GithubLink"},"here"),"."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app.py"',title:'"my_app.py"'},'from omegaconf import DictConfig, OmegaConf\nimport hydra\n\n@hydra.main(version_base=None)\ndef my_app(cfg: DictConfig) -> None:\n print(OmegaConf.to_yaml(cfg))\n\nif __name__ == "__main__":\n my_app()\n')),(0,i.mdx)("p",null,"In this example, Hydra creates an empty ",(0,i.mdx)("inlineCode",{parentName:"p"},"cfg")," object and passes it to the function annotated with ",(0,i.mdx)("inlineCode",{parentName:"p"},"@hydra.main"),"."),(0,i.mdx)("p",null,"You can add config values via the command line. The ",(0,i.mdx)("inlineCode",{parentName:"p"},"+")," indicates that the field is new."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py +db.driver=mysql +db.user=omry +db.password=secret\ndb:\n driver: mysql\n user: omry\n password: secret\n")),(0,i.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,i.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,i.mdx)("h5",{parentName:"div"},(0,i.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,i.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,i.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"info")),(0,i.mdx)("div",{parentName:"div",className:"admonition-content"},(0,i.mdx)("p",{parentName:"div"},"See the ",(0,i.mdx)("a",{parentName:"p",href:"/docs/upgrades/version_base"},"version_base page")," for details on the version_base parameter."))),(0,i.mdx)("p",null,"See ",(0,i.mdx)("a",{parentName:"p",href:"/docs/advanced/hydra-command-line-flags"},"Hydra's command line flags")," and\n",(0,i.mdx)("a",{parentName:"p",href:"/docs/advanced/override_grammar/basic"},"Basic Override Syntax")," for more information about the command line."))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/27af8fe6.ea46fa38.js b/assets/js/27af8fe6.ea46fa38.js new file mode 100644 index 0000000000..97669b651d --- /dev/null +++ b/assets/js/27af8fe6.ea46fa38.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[4312],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>s,MDXProvider:()=>d,mdx:()=>y,useMDXComponents:()=>c,withMDXComponents:()=>m});var a=n(96540);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(){return i=Object.assign||function(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var s=a.createContext({}),m=function(e){return function(t){var n=c(t.components);return a.createElement(e,i({},t,{components:n}))}},c=function(e){var t=a.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},d=function(e){var t=c(e.components);return a.createElement(s.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},f=a.forwardRef((function(e,t){var n=e.components,r=e.mdxType,i=e.originalType,o=e.parentName,s=p(e,["components","mdxType","originalType","parentName"]),m=c(n),d=r,f=m["".concat(o,".").concat(d)]||m[d]||u[d]||i;return n?a.createElement(f,l(l({ref:t},s),{},{components:n})):a.createElement(f,l({ref:t},s))}));function y(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var i=n.length,o=new Array(i);o[0]=f;var l={};for(var p in t)hasOwnProperty.call(t,p)&&(l[p]=t[p]);l.originalType=e,l.mdxType="string"==typeof e?e:r,o[1]=l;for(var s=2;s{n.d(t,{A:()=>p,C:()=>s});var a=n(58168),r=n(96540),i=n(75489),o=n(44586),l=n(74098);function p(e){return r.createElement(i.default,(0,a.A)({},e,{to:(t=e.to,p=(0,l.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==p?void 0:p.name)?n:"current"]+t),target:"_blank"}));var t,n,p}function s(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return r.createElement(p,e,r.createElement("span",null,"\xa0"),r.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},40147:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>s,default:()=>u,frontMatter:()=>p,metadata:()=>m,toc:()=>c});var a=n(58168),r=n(98587),i=(n(96540),n(15680)),o=n(49595),l=["components"],p={id:"simple_cli",title:"A simple command-line application"},s=void 0,m={unversionedId:"tutorials/basic/your_first_app/simple_cli",id:"tutorials/basic/your_first_app/simple_cli",title:"A simple command-line application",description:"This is a simple Hydra application that prints your configuration.",source:"@site/docs/tutorials/basic/your_first_app/1_simple_cli.md",sourceDirName:"tutorials/basic/your_first_app",slug:"/tutorials/basic/your_first_app/simple_cli",permalink:"/docs/tutorials/basic/your_first_app/simple_cli",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/tutorials/basic/your_first_app/1_simple_cli.md",tags:[],version:"current",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:1,frontMatter:{id:"simple_cli",title:"A simple command-line application"},sidebar:"docs",previous:{title:"Tutorials intro",permalink:"/docs/tutorials/intro"},next:{title:"Specifying a config file",permalink:"/docs/tutorials/basic/your_first_app/config_file"}},c=[],d={toc:c};function u(e){var t=e.components,n=(0,r.A)(e,l);return(0,i.mdx)("wrapper",(0,a.A)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,i.mdx)(o.C,{to:"examples/tutorials/basic/your_first_hydra_app/1_simple_cli/my_app.py",mdxType:"ExampleGithubLink"}),(0,i.mdx)("p",null,"This is a simple Hydra application that prints your configuration.\nThe ",(0,i.mdx)("inlineCode",{parentName:"p"},"my_app")," function is a placeholder for your code.\nWe will slowly evolve this example to showcase more Hydra features."),(0,i.mdx)("p",null,"The examples in this tutorial are available ",(0,i.mdx)(o.A,{to:"examples/tutorials/basic",mdxType:"GithubLink"},"here"),"."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app.py"',title:'"my_app.py"'},'from omegaconf import DictConfig, OmegaConf\nimport hydra\n\n@hydra.main(version_base=None)\ndef my_app(cfg: DictConfig) -> None:\n print(OmegaConf.to_yaml(cfg))\n\nif __name__ == "__main__":\n my_app()\n')),(0,i.mdx)("p",null,"In this example, Hydra creates an empty ",(0,i.mdx)("inlineCode",{parentName:"p"},"cfg")," object and passes it to the function annotated with ",(0,i.mdx)("inlineCode",{parentName:"p"},"@hydra.main"),"."),(0,i.mdx)("p",null,"You can add config values via the command line. The ",(0,i.mdx)("inlineCode",{parentName:"p"},"+")," indicates that the field is new."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py +db.driver=mysql +db.user=omry +db.password=secret\ndb:\n driver: mysql\n user: omry\n password: secret\n")),(0,i.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,i.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,i.mdx)("h5",{parentName:"div"},(0,i.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,i.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,i.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"info")),(0,i.mdx)("div",{parentName:"div",className:"admonition-content"},(0,i.mdx)("p",{parentName:"div"},"See the ",(0,i.mdx)("a",{parentName:"p",href:"/docs/upgrades/version_base"},"version_base page")," for details on the version_base parameter."))),(0,i.mdx)("p",null,"See ",(0,i.mdx)("a",{parentName:"p",href:"/docs/advanced/hydra-command-line-flags"},"Hydra's command line flags")," and\n",(0,i.mdx)("a",{parentName:"p",href:"/docs/advanced/override_grammar/basic"},"Basic Override Syntax")," for more information about the command line."))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/27f5d38d.0c44ee25.js b/assets/js/27f5d38d.0c44ee25.js new file mode 100644 index 0000000000..6bef7b087d --- /dev/null +++ b/assets/js/27f5d38d.0c44ee25.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[126],{15680:(e,r,t)=>{t.r(r),t.d(r,{MDXContext:()=>p,MDXProvider:()=>m,mdx:()=>f,useMDXComponents:()=>c,withMDXComponents:()=>u});var o=t(96540);function n(e,r,t){return r in e?Object.defineProperty(e,r,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[r]=t,e}function i(){return i=Object.assign||function(e){for(var r=1;r=0||(n[t]=e[t]);return n}(e,r);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(o=0;o=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(n[t]=e[t])}return n}var p=o.createContext({}),u=function(e){return function(r){var t=c(r.components);return o.createElement(e,i({},r,{components:t}))}},c=function(e){var r=o.useContext(p),t=r;return e&&(t="function"==typeof e?e(r):l(l({},r),e)),t},m=function(e){var r=c(e.components);return o.createElement(p.Provider,{value:r},e.children)},y={inlineCode:"code",wrapper:function(e){var r=e.children;return o.createElement(o.Fragment,{},r)}},s=o.forwardRef((function(e,r){var t=e.components,n=e.mdxType,i=e.originalType,a=e.parentName,p=d(e,["components","mdxType","originalType","parentName"]),u=c(t),m=n,s=u["".concat(a,".").concat(m)]||u[m]||y[m]||i;return t?o.createElement(s,l(l({ref:r},p),{},{components:t})):o.createElement(s,l({ref:r},p))}));function f(e,r){var t=arguments,n=r&&r.mdxType;if("string"==typeof e||n){var i=t.length,a=new Array(i);a[0]=s;var l={};for(var d in r)hasOwnProperty.call(r,d)&&(l[d]=r[d]);l.originalType=e,l.mdxType="string"==typeof e?e:n,a[1]=l;for(var p=2;p{t.r(r),t.d(r,{contentTitle:()=>d,default:()=>m,frontMatter:()=>l,metadata:()=>p,toc:()=>u});var o=t(58168),n=t(98587),i=(t(96540),t(15680)),a=["components"],l={id:"working_directory",title:"Output/Working directory",sidebar_label:"Output/Working directory"},d=void 0,p={unversionedId:"tutorial/working_directory",id:"version-0.11/tutorial/working_directory",title:"Output/Working directory",description:"Hydra solves the problem of your needing to specify a new output directory for each run, by",source:"@site/versioned_docs/version-0.11/tutorial/8_working_directory.md",sourceDirName:"tutorial",slug:"/tutorial/working_directory",permalink:"/docs/0.11/tutorial/working_directory",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-0.11/tutorial/8_working_directory.md",tags:[],version:"0.11",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:8,frontMatter:{id:"working_directory",title:"Output/Working directory",sidebar_label:"Output/Working directory"},sidebar:"version-0.11/docs",previous:{title:"Tab completion",permalink:"/docs/0.11/tutorial/tab_completion"},next:{title:"Logging",permalink:"/docs/0.11/tutorial/logging"}},u=[{value:"Original working directory",id:"original-working-directory",children:[],level:3}],c={toc:u};function m(e){var r=e.components,t=(0,n.A)(e,a);return(0,i.mdx)("wrapper",(0,o.A)({},c,t,{components:r,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Hydra solves the problem of your needing to specify a new output directory for each run, by\ncreating a directory for each run and executing your code within that directory."),(0,i.mdx)("p",null,"The working directory is used to:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"Store the output for the application (For example, a database dump file)"),(0,i.mdx)("li",{parentName:"ul"},"Store the Hydra output for the run (Configuration, Logs etc)")),(0,i.mdx)("p",null,"Every time you run the app, a new working directory is automatically created:"),(0,i.mdx)("p",null,"Python file: ",(0,i.mdx)("inlineCode",{parentName:"p"},"my_app.py")),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python"},'import os\n\n@hydra.main()\ndef my_app(_cfg):\n print("Working directory : {}".format(os.getcwd()))\n\n$ python my_app.py\nWorking directory : /home/omry/dev/hydra/outputs/2019-09-25/15-16-17\n\n$ python my_app.py\nWorking directory : /home/omry/dev/hydra/outputs/2019-09-25/15-16-19\n')),(0,i.mdx)("p",null,"Let's take a look at one of those working directories:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text"},"$ tree outputs/2019-09-25/15-16-17\noutputs/2019-09-25/15-16-17\n\u251c\u2500\u2500 .hydra\n\u2502 \u251c\u2500\u2500 config.yaml\n\u2502 \u251c\u2500\u2500 hydra.yaml\n\u2502 \u2514\u2500\u2500 overrides.yaml\n\u2514\u2500\u2500 my_app.log\n")),(0,i.mdx)("p",null,"We have the Hydra output directory (",(0,i.mdx)("inlineCode",{parentName:"p"},".hydra")," by default) and the application log file.\nInside the configuration output directory we have:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"config.yaml"),": A dump of the user specified configuration"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"hydra.yaml"),": A dump of the Hydra configuration"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"overrides.yaml"),": The command line overrides used")),(0,i.mdx)("p",null,"And in the main output directory:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"my_app.log"),": A log file created for this run")),(0,i.mdx)("h3",{id:"original-working-directory"},"Original working directory"),(0,i.mdx)("p",null,"You can still access the original working directory if you need to:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python"},'import os\nimport hydra\nfrom hydra import utils\n\n@hydra.main()\ndef my_app(_cfg):\n print("Current working directory : {}".format(os.getcwd()))\n print("Original working directory : {}".format(utils.get_original_cwd()))\n print("to_absolute_path(\'foo\') : {}".format(utils.to_absolute_path("foo")))\n print("to_absolute_path(\'/foo\') : {}".format(utils.to_absolute_path("/foo")))\n\n\n$ python examples/tutorial/8_working_directory/original_cwd.py\nCurrent working directory : /Users/omry/dev/hydra/outputs/2019-10-23/10-53-03\nOriginal working directory : /Users/omry/dev/hydra\nto_absolute_path(\'foo\') : /Users/omry/dev/hydra/foo\nto_absolute_path(\'/foo\') : /foo\n')),(0,i.mdx)("p",null,"Working directory can be ",(0,i.mdx)("a",{parentName:"p",href:"/docs/0.11/configure_hydra/workdir"},"customized"),"."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/27f5d38d.e0be3dc1.js b/assets/js/27f5d38d.e0be3dc1.js deleted file mode 100644 index 0757c63e00..0000000000 --- a/assets/js/27f5d38d.e0be3dc1.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[126],{15680:(e,r,t)=>{t.r(r),t.d(r,{MDXContext:()=>p,MDXProvider:()=>m,mdx:()=>f,useMDXComponents:()=>c,withMDXComponents:()=>u});var o=t(96540);function n(e,r,t){return r in e?Object.defineProperty(e,r,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[r]=t,e}function i(){return i=Object.assign||function(e){for(var r=1;r=0||(n[t]=e[t]);return n}(e,r);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(o=0;o=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(n[t]=e[t])}return n}var p=o.createContext({}),u=function(e){return function(r){var t=c(r.components);return o.createElement(e,i({},r,{components:t}))}},c=function(e){var r=o.useContext(p),t=r;return e&&(t="function"==typeof e?e(r):l(l({},r),e)),t},m=function(e){var r=c(e.components);return o.createElement(p.Provider,{value:r},e.children)},y={inlineCode:"code",wrapper:function(e){var r=e.children;return o.createElement(o.Fragment,{},r)}},s=o.forwardRef((function(e,r){var t=e.components,n=e.mdxType,i=e.originalType,a=e.parentName,p=d(e,["components","mdxType","originalType","parentName"]),u=c(t),m=n,s=u["".concat(a,".").concat(m)]||u[m]||y[m]||i;return t?o.createElement(s,l(l({ref:r},p),{},{components:t})):o.createElement(s,l({ref:r},p))}));function f(e,r){var t=arguments,n=r&&r.mdxType;if("string"==typeof e||n){var i=t.length,a=new Array(i);a[0]=s;var l={};for(var d in r)hasOwnProperty.call(r,d)&&(l[d]=r[d]);l.originalType=e,l.mdxType="string"==typeof e?e:n,a[1]=l;for(var p=2;p{t.r(r),t.d(r,{contentTitle:()=>d,default:()=>m,frontMatter:()=>l,metadata:()=>p,toc:()=>u});var o=t(58168),n=t(98587),i=(t(96540),t(15680)),a=["components"],l={id:"working_directory",title:"Output/Working directory",sidebar_label:"Output/Working directory"},d=void 0,p={unversionedId:"tutorial/working_directory",id:"version-0.11/tutorial/working_directory",title:"Output/Working directory",description:"Hydra solves the problem of your needing to specify a new output directory for each run, by",source:"@site/versioned_docs/version-0.11/tutorial/8_working_directory.md",sourceDirName:"tutorial",slug:"/tutorial/working_directory",permalink:"/docs/0.11/tutorial/working_directory",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-0.11/tutorial/8_working_directory.md",tags:[],version:"0.11",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:8,frontMatter:{id:"working_directory",title:"Output/Working directory",sidebar_label:"Output/Working directory"},sidebar:"version-0.11/docs",previous:{title:"Tab completion",permalink:"/docs/0.11/tutorial/tab_completion"},next:{title:"Logging",permalink:"/docs/0.11/tutorial/logging"}},u=[{value:"Original working directory",id:"original-working-directory",children:[],level:3}],c={toc:u};function m(e){var r=e.components,t=(0,n.A)(e,a);return(0,i.mdx)("wrapper",(0,o.A)({},c,t,{components:r,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Hydra solves the problem of your needing to specify a new output directory for each run, by\ncreating a directory for each run and executing your code within that directory."),(0,i.mdx)("p",null,"The working directory is used to:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"Store the output for the application (For example, a database dump file)"),(0,i.mdx)("li",{parentName:"ul"},"Store the Hydra output for the run (Configuration, Logs etc)")),(0,i.mdx)("p",null,"Every time you run the app, a new working directory is automatically created:"),(0,i.mdx)("p",null,"Python file: ",(0,i.mdx)("inlineCode",{parentName:"p"},"my_app.py")),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python"},'import os\n\n@hydra.main()\ndef my_app(_cfg):\n print("Working directory : {}".format(os.getcwd()))\n\n$ python my_app.py\nWorking directory : /home/omry/dev/hydra/outputs/2019-09-25/15-16-17\n\n$ python my_app.py\nWorking directory : /home/omry/dev/hydra/outputs/2019-09-25/15-16-19\n')),(0,i.mdx)("p",null,"Let's take a look at one of those working directories:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text"},"$ tree outputs/2019-09-25/15-16-17\noutputs/2019-09-25/15-16-17\n\u251c\u2500\u2500 .hydra\n\u2502 \u251c\u2500\u2500 config.yaml\n\u2502 \u251c\u2500\u2500 hydra.yaml\n\u2502 \u2514\u2500\u2500 overrides.yaml\n\u2514\u2500\u2500 my_app.log\n")),(0,i.mdx)("p",null,"We have the Hydra output directory (",(0,i.mdx)("inlineCode",{parentName:"p"},".hydra")," by default) and the application log file.\nInside the configuration output directory we have:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"config.yaml"),": A dump of the user specified configuration"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"hydra.yaml"),": A dump of the Hydra configuration"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"overrides.yaml"),": The command line overrides used")),(0,i.mdx)("p",null,"And in the main output directory:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"my_app.log"),": A log file created for this run")),(0,i.mdx)("h3",{id:"original-working-directory"},"Original working directory"),(0,i.mdx)("p",null,"You can still access the original working directory if you need to:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python"},'import os\nimport hydra\nfrom hydra import utils\n\n@hydra.main()\ndef my_app(_cfg):\n print("Current working directory : {}".format(os.getcwd()))\n print("Original working directory : {}".format(utils.get_original_cwd()))\n print("to_absolute_path(\'foo\') : {}".format(utils.to_absolute_path("foo")))\n print("to_absolute_path(\'/foo\') : {}".format(utils.to_absolute_path("/foo")))\n\n\n$ python examples/tutorial/8_working_directory/original_cwd.py\nCurrent working directory : /Users/omry/dev/hydra/outputs/2019-10-23/10-53-03\nOriginal working directory : /Users/omry/dev/hydra\nto_absolute_path(\'foo\') : /Users/omry/dev/hydra/foo\nto_absolute_path(\'/foo\') : /foo\n')),(0,i.mdx)("p",null,"Working directory can be ",(0,i.mdx)("a",{parentName:"p",href:"/docs/0.11/configure_hydra/workdir"},"customized"),"."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2862967f.04c66b9f.js b/assets/js/2862967f.04c66b9f.js new file mode 100644 index 0000000000..e6f52d19d9 --- /dev/null +++ b/assets/js/2862967f.04c66b9f.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[6835],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>d,MDXProvider:()=>p,mdx:()=>g,useMDXComponents:()=>c,withMDXComponents:()=>m});var a=n(96540);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var d=a.createContext({}),m=function(e){return function(t){var n=c(t.components);return a.createElement(e,o({},t,{components:n}))}},c=function(e){var t=a.useContext(d),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},p=function(e){var t=c(e.components);return a.createElement(d.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},f=a.forwardRef((function(e,t){var n=e.components,i=e.mdxType,o=e.originalType,r=e.parentName,d=s(e,["components","mdxType","originalType","parentName"]),m=c(n),p=i,f=m["".concat(r,".").concat(p)]||m[p]||u[p]||o;return n?a.createElement(f,l(l({ref:t},d),{},{components:n})):a.createElement(f,l({ref:t},d))}));function g(e,t){var n=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var o=n.length,r=new Array(o);r[0]=f;var l={};for(var s in t)hasOwnProperty.call(t,s)&&(l[s]=t[s]);l.originalType=e,l.mdxType="string"==typeof e?e:i,r[1]=l;for(var d=2;d{n.r(t),n.d(t,{contentTitle:()=>s,default:()=>p,frontMatter:()=>l,metadata:()=>d,toc:()=>m});var a=n(58168),i=n(98587),o=(n(96540),n(15680)),r=["components"],l={id:"default_composition_order",title:"Changes to default composition order"},s=void 0,d={unversionedId:"upgrades/1.0_to_1.1/default_composition_order",id:"version-1.2/upgrades/1.0_to_1.1/default_composition_order",title:"Changes to default composition order",description:"Default composition order is changing in Hydra 1.1.",source:"@site/versioned_docs/version-1.2/upgrades/1.0_to_1.1/changes_to_default_composition_order.md",sourceDirName:"upgrades/1.0_to_1.1",slug:"/upgrades/1.0_to_1.1/default_composition_order",permalink:"/docs/1.2/upgrades/1.0_to_1.1/default_composition_order",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/upgrades/1.0_to_1.1/changes_to_default_composition_order.md",tags:[],version:"1.2",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"default_composition_order",title:"Changes to default composition order"},sidebar:"docs",previous:{title:"Changes to @hydra.main() and hydra.initialize()",permalink:"/docs/1.2/upgrades/1.0_to_1.1/changes_to_hydra_main_config_path"},next:{title:"Defaults List Overrides",permalink:"/docs/1.2/upgrades/1.0_to_1.1/defaults_list_override"}},m=[{value:"Migration",id:"migration",children:[{value:"Primary config is a YAML file",id:"primary-config-is-a-yaml-file",children:[],level:3},{value:"Primary config is a Structured Config",id:"primary-config-is-a-structured-config",children:[],level:3},{value:"Primary config is a config file with a Structured Config schema",id:"primary-config-is-a-config-file-with-a-structured-config-schema",children:[],level:3},{value:"Compatibility with both Hydra 1.0 and 1.1",id:"compatibility-with-both-hydra-10-and-11",children:[],level:3}],level:2}],c={toc:m};function p(e){var t=e.components,n=(0,i.A)(e,r);return(0,o.mdx)("wrapper",(0,a.A)({},c,n,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"Default composition order is changing in Hydra 1.1."),(0,o.mdx)("p",null,"For this example, let's assume the following two configs:"),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - foo: bar\n\nfoo:\n x: 10\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="foo/bar.yaml"',title:'"foo/bar.yaml"'},"# @package _group_\nx: 20\n\n\n\n")))),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col"},(0,o.mdx)("p",null,"In ",(0,o.mdx)("strong",{parentName:"p"},"Hydra 1.0"),", configs from the Defaults List are overriding ",(0,o.mdx)("em",{parentName:"p"},"config.yaml"),", resulting in the following output:")),(0,o.mdx)("div",{className:"col col--4"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{2}","{2}":!0},"foo:\n x: 20\n")))),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col"},(0,o.mdx)("p",null,"As of ",(0,o.mdx)("strong",{parentName:"p"},"Hydra 1.1"),", ",(0,o.mdx)("em",{parentName:"p"},"config.yaml")," is overriding configs from the Defaults List, resulting in the following output:")),(0,o.mdx)("div",{className:"col col--4"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{2}","{2}":!0},"foo:\n x: 10\n")))),(0,o.mdx)("h2",{id:"migration"},"Migration"),(0,o.mdx)("p",null,"If your application uses ",(0,o.mdx)("inlineCode",{parentName:"p"},"hydra.main"),", the best way to verify that updating Hydra versions does not change your job configurations is to compare the output of ",(0,o.mdx)("inlineCode",{parentName:"p"},"python my_app.py --cfg job")," on both the new and old Hydra versions. If your application uses the Compose API, please make sure you have comprehensive unit tests on the composed configuration."),(0,o.mdx)("h3",{id:"primary-config-is-a-yaml-file"},"Primary config is a YAML file"),(0,o.mdx)("p",null,"To ensure this change is not missed by people migrating from Hydra 1.0, Hydra 1.1 issues a warning if the Defaults List in the primary config is missing ",(0,o.mdx)("inlineCode",{parentName:"p"},"_self_"),", and there are config values in addition to the Defaults List.",(0,o.mdx)("br",{parentName:"p"}),"\n","To address the warning, add ",(0,o.mdx)("inlineCode",{parentName:"p"},"_self_")," to the Defaults List of the primary config."),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"If the new behavior works for your application, append ",(0,o.mdx)("inlineCode",{parentName:"li"},"_self_")," to the end of the Defaults List."),(0,o.mdx)("li",{parentName:"ul"},"If your application requires the previous behavior, insert ",(0,o.mdx)("inlineCode",{parentName:"li"},"_self_")," as the first item in your Defaults List.")),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {2}',title:'"config.yaml"',"{2}":!0},"defaults:\n - _self_\n - foo: bar\n\nfoo:\n x: 10\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Output config"',title:'"Output','config"':!0},"foo:\n x: 20\n\n\n\n\n")))),(0,o.mdx)("p",null,"The Defaults List is described ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.2/advanced/defaults_list"},"here"),"."),(0,o.mdx)("h3",{id:"primary-config-is-a-structured-config"},"Primary config is a Structured Config"),(0,o.mdx)("p",null,"Structured Configs used as primary config may see changes as well.\nYou should add ",(0,o.mdx)("inlineCode",{parentName:"p"},"_self_")," to the defaults list to indicate the composition order. In such cases you will typically want ",(0,o.mdx)("inlineCode",{parentName:"p"},"_self_")," to be the first item in the defaults list. "),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:"{3,14}","{3,14}":!0},'defaults = [\n "_self_",\n {"db": "mysql"}\n]\n\n@dataclass\nclass Config:\n # this is unfortunately verbose due to @dataclass limitations\n defaults: List[Any] = field(default_factory=lambda: defaults)\n\n # Hydra will populate this field based on the defaults list\n db: Any = MISSING\n')),(0,o.mdx)("h3",{id:"primary-config-is-a-config-file-with-a-structured-config-schema"},"Primary config is a config file with a Structured Config schema"),(0,o.mdx)("p",null,"If you use Structured Config as a schema for your primary config, be sure to add ",(0,o.mdx)("inlineCode",{parentName:"p"},"_self_")," after the schema in the Defaults List, otherwise the schema will override the config instead of the other way around."),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--4"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app.py"',title:'"my_app.py"'},'@dataclass\nclass Config:\n host: str = "localhost"\n port: int = 8080\n\ncs.store(name="base_config", \n node=Config)\n'))),(0,o.mdx)("div",{className:"col col--4"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'{3,5} title="config.yaml"',"{3,5}":!0,title:'"config.yaml"'},"defaults:\n - base_config # schema\n - _self_ # after schema\n\nport: 3306\n\n\n"))),(0,o.mdx)("div",{className:"col col--4"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'{2} title="Output config"',"{2}":!0,title:'"Output','config"':!0},"host: localhost # schema\nport: 3306 # config.yaml\n\n\n\n\n\n")))),(0,o.mdx)("h3",{id:"compatibility-with-both-hydra-10-and-11"},"Compatibility with both Hydra 1.0 and 1.1"),(0,o.mdx)("p",null,"If your config must be compatible with both Hydra 1.0 and 1.1, Insert ",(0,o.mdx)("inlineCode",{parentName:"p"},"_self_")," as the first item in the Defaults List.\nHydra 1.0.7 (or newer releases in Hydra 1.0) ignores ",(0,o.mdx)("inlineCode",{parentName:"p"},"_self_")," in the Defaults List and Hydra 1.1 will compose the same config as Hydra 1.0 if ",(0,o.mdx)("inlineCode",{parentName:"p"},"_self_")," is the first item."))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2862967f.703dbe91.js b/assets/js/2862967f.703dbe91.js deleted file mode 100644 index 620cde5743..0000000000 --- a/assets/js/2862967f.703dbe91.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[6835],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>d,MDXProvider:()=>p,mdx:()=>g,useMDXComponents:()=>c,withMDXComponents:()=>m});var a=n(96540);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function r(){return r=Object.assign||function(e){for(var t=1;t=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var d=a.createContext({}),m=function(e){return function(t){var n=c(t.components);return a.createElement(e,r({},t,{components:n}))}},c=function(e){var t=a.useContext(d),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},p=function(e){var t=c(e.components);return a.createElement(d.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},f=a.forwardRef((function(e,t){var n=e.components,i=e.mdxType,r=e.originalType,o=e.parentName,d=s(e,["components","mdxType","originalType","parentName"]),m=c(n),p=i,f=m["".concat(o,".").concat(p)]||m[p]||u[p]||r;return n?a.createElement(f,l(l({ref:t},d),{},{components:n})):a.createElement(f,l({ref:t},d))}));function g(e,t){var n=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var r=n.length,o=new Array(r);o[0]=f;var l={};for(var s in t)hasOwnProperty.call(t,s)&&(l[s]=t[s]);l.originalType=e,l.mdxType="string"==typeof e?e:i,o[1]=l;for(var d=2;d{n.r(t),n.d(t,{contentTitle:()=>s,default:()=>p,frontMatter:()=>l,metadata:()=>d,toc:()=>m});var a=n(58168),i=n(98587),r=(n(96540),n(15680)),o=["components"],l={id:"default_composition_order",title:"Changes to default composition order"},s=void 0,d={unversionedId:"upgrades/1.0_to_1.1/default_composition_order",id:"version-1.2/upgrades/1.0_to_1.1/default_composition_order",title:"Changes to default composition order",description:"Default composition order is changing in Hydra 1.1.",source:"@site/versioned_docs/version-1.2/upgrades/1.0_to_1.1/changes_to_default_composition_order.md",sourceDirName:"upgrades/1.0_to_1.1",slug:"/upgrades/1.0_to_1.1/default_composition_order",permalink:"/docs/1.2/upgrades/1.0_to_1.1/default_composition_order",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/upgrades/1.0_to_1.1/changes_to_default_composition_order.md",tags:[],version:"1.2",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"default_composition_order",title:"Changes to default composition order"},sidebar:"docs",previous:{title:"Changes to @hydra.main() and hydra.initialize()",permalink:"/docs/1.2/upgrades/1.0_to_1.1/changes_to_hydra_main_config_path"},next:{title:"Defaults List Overrides",permalink:"/docs/1.2/upgrades/1.0_to_1.1/defaults_list_override"}},m=[{value:"Migration",id:"migration",children:[{value:"Primary config is a YAML file",id:"primary-config-is-a-yaml-file",children:[],level:3},{value:"Primary config is a Structured Config",id:"primary-config-is-a-structured-config",children:[],level:3},{value:"Primary config is a config file with a Structured Config schema",id:"primary-config-is-a-config-file-with-a-structured-config-schema",children:[],level:3},{value:"Compatibility with both Hydra 1.0 and 1.1",id:"compatibility-with-both-hydra-10-and-11",children:[],level:3}],level:2}],c={toc:m};function p(e){var t=e.components,n=(0,i.A)(e,o);return(0,r.mdx)("wrapper",(0,a.A)({},c,n,{components:t,mdxType:"MDXLayout"}),(0,r.mdx)("p",null,"Default composition order is changing in Hydra 1.1."),(0,r.mdx)("p",null,"For this example, let's assume the following two configs:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - foo: bar\n\nfoo:\n x: 10\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="foo/bar.yaml"',title:'"foo/bar.yaml"'},"# @package _group_\nx: 20\n\n\n\n")))),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col"},(0,r.mdx)("p",null,"In ",(0,r.mdx)("strong",{parentName:"p"},"Hydra 1.0"),", configs from the Defaults List are overriding ",(0,r.mdx)("em",{parentName:"p"},"config.yaml"),", resulting in the following output:")),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{2}","{2}":!0},"foo:\n x: 20\n")))),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col"},(0,r.mdx)("p",null,"As of ",(0,r.mdx)("strong",{parentName:"p"},"Hydra 1.1"),", ",(0,r.mdx)("em",{parentName:"p"},"config.yaml")," is overriding configs from the Defaults List, resulting in the following output:")),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{2}","{2}":!0},"foo:\n x: 10\n")))),(0,r.mdx)("h2",{id:"migration"},"Migration"),(0,r.mdx)("p",null,"If your application uses ",(0,r.mdx)("inlineCode",{parentName:"p"},"hydra.main"),", the best way to verify that updating Hydra versions does not change your job configurations is to compare the output of ",(0,r.mdx)("inlineCode",{parentName:"p"},"python my_app.py --cfg job")," on both the new and old Hydra versions. If your application uses the Compose API, please make sure you have comprehensive unit tests on the composed configuration."),(0,r.mdx)("h3",{id:"primary-config-is-a-yaml-file"},"Primary config is a YAML file"),(0,r.mdx)("p",null,"To ensure this change is not missed by people migrating from Hydra 1.0, Hydra 1.1 issues a warning if the Defaults List in the primary config is missing ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_"),", and there are config values in addition to the Defaults List.",(0,r.mdx)("br",{parentName:"p"}),"\n","To address the warning, add ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," to the Defaults List of the primary config."),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"If the new behavior works for your application, append ",(0,r.mdx)("inlineCode",{parentName:"li"},"_self_")," to the end of the Defaults List."),(0,r.mdx)("li",{parentName:"ul"},"If your application requires the previous behavior, insert ",(0,r.mdx)("inlineCode",{parentName:"li"},"_self_")," as the first item in your Defaults List.")),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {2}',title:'"config.yaml"',"{2}":!0},"defaults:\n - _self_\n - foo: bar\n\nfoo:\n x: 10\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Output config"',title:'"Output','config"':!0},"foo:\n x: 20\n\n\n\n\n")))),(0,r.mdx)("p",null,"The Defaults List is described ",(0,r.mdx)("a",{parentName:"p",href:"/docs/1.2/advanced/defaults_list"},"here"),"."),(0,r.mdx)("h3",{id:"primary-config-is-a-structured-config"},"Primary config is a Structured Config"),(0,r.mdx)("p",null,"Structured Configs used as primary config may see changes as well.\nYou should add ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," to the defaults list to indicate the composition order. In such cases you will typically want ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," to be the first item in the defaults list. "),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python",metastring:"{3,14}","{3,14}":!0},'defaults = [\n "_self_",\n {"db": "mysql"}\n]\n\n@dataclass\nclass Config:\n # this is unfortunately verbose due to @dataclass limitations\n defaults: List[Any] = field(default_factory=lambda: defaults)\n\n # Hydra will populate this field based on the defaults list\n db: Any = MISSING\n')),(0,r.mdx)("h3",{id:"primary-config-is-a-config-file-with-a-structured-config-schema"},"Primary config is a config file with a Structured Config schema"),(0,r.mdx)("p",null,"If you use Structured Config as a schema for your primary config, be sure to add ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," after the schema in the Defaults List, otherwise the schema will override the config instead of the other way around."),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app.py"',title:'"my_app.py"'},'@dataclass\nclass Config:\n host: str = "localhost"\n port: int = 8080\n\ncs.store(name="base_config", \n node=Config)\n'))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'{3,5} title="config.yaml"',"{3,5}":!0,title:'"config.yaml"'},"defaults:\n - base_config # schema\n - _self_ # after schema\n\nport: 3306\n\n\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'{2} title="Output config"',"{2}":!0,title:'"Output','config"':!0},"host: localhost # schema\nport: 3306 # config.yaml\n\n\n\n\n\n")))),(0,r.mdx)("h3",{id:"compatibility-with-both-hydra-10-and-11"},"Compatibility with both Hydra 1.0 and 1.1"),(0,r.mdx)("p",null,"If your config must be compatible with both Hydra 1.0 and 1.1, Insert ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," as the first item in the Defaults List.\nHydra 1.0.7 (or newer releases in Hydra 1.0) ignores ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," in the Defaults List and Hydra 1.1 will compose the same config as Hydra 1.0 if ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," is the first item."))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/28a7fcb4.9e0e9e40.js b/assets/js/28a7fcb4.9e0e9e40.js deleted file mode 100644 index 612b762ba1..0000000000 --- a/assets/js/28a7fcb4.9e0e9e40.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[6138],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>m,MDXProvider:()=>u,mdx:()=>y,useMDXComponents:()=>s,withMDXComponents:()=>p});var t=a(96540);function r(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(r[a]=e[a]);return r}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(r[a]=e[a])}return r}var m=t.createContext({}),p=function(e){return function(n){var a=s(n.components);return t.createElement(e,i({},n,{components:a}))}},s=function(e){var n=t.useContext(m),a=n;return e&&(a="function"==typeof e?e(n):l(l({},n),e)),a},u=function(e){var n=s(e.components);return t.createElement(m.Provider,{value:n},e.children)},c={inlineCode:"code",wrapper:function(e){var n=e.children;return t.createElement(t.Fragment,{},n)}},h=t.forwardRef((function(e,n){var a=e.components,r=e.mdxType,i=e.originalType,o=e.parentName,m=d(e,["components","mdxType","originalType","parentName"]),p=s(a),u=r,h=p["".concat(o,".").concat(u)]||p[u]||c[u]||i;return a?t.createElement(h,l(l({ref:n},m),{},{components:a})):t.createElement(h,l({ref:n},m))}));function y(e,n){var a=arguments,r=n&&n.mdxType;if("string"==typeof e||r){var i=a.length,o=new Array(i);o[0]=h;var l={};for(var d in n)hasOwnProperty.call(n,d)&&(l[d]=n[d]);l.originalType=e,l.mdxType="string"==typeof e?e:r,o[1]=l;for(var m=2;m{a.d(n,{A:()=>d,C:()=>m});var t=a(58168),r=a(96540),i=a(75489),o=a(44586),l=a(74098);function d(e){return r.createElement(i.default,(0,t.A)({},e,{to:(n=e.to,d=(0,l.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(a=null==d?void 0:d.name)?a:"current"]+n),target:"_blank"}));var n,a,d}function m(e){var n,a=null!=(n=e.text)?n:"Example (Click Here)";return r.createElement(d,e,r.createElement("span",null,"\xa0"),r.createElement("img",{src:"https://img.shields.io/badge/-"+a+"-informational",alt:"Example (Click Here)"}))}},46417:(e,n,a)=>{a.r(n),a.d(n,{contentTitle:()=>m,default:()=>c,frontMatter:()=>d,metadata:()=>p,toc:()=>s});var t=a(58168),r=a(98587),i=(a(96540),a(15680)),o=a(49595),l=["components"],d={id:"multi-run",title:"Multi-run",sidebar_label:"Multi-run"},m=void 0,p={unversionedId:"tutorials/basic/running_your_app/multi-run",id:"version-1.2/tutorials/basic/running_your_app/multi-run",title:"Multi-run",description:"Sometimes you want to run the same application with multiple different configurations.",source:"@site/versioned_docs/version-1.2/tutorials/basic/running_your_app/2_multirun.md",sourceDirName:"tutorials/basic/running_your_app",slug:"/tutorials/basic/running_your_app/multi-run",permalink:"/docs/1.2/tutorials/basic/running_your_app/multi-run",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/tutorials/basic/running_your_app/2_multirun.md",tags:[],version:"1.2",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:2,frontMatter:{id:"multi-run",title:"Multi-run",sidebar_label:"Multi-run"},sidebar:"docs",previous:{title:"Putting it all together",permalink:"/docs/1.2/tutorials/basic/your_first_app/composition"},next:{title:"Output/Working directory",permalink:"/docs/1.2/tutorials/basic/running_your_app/working_directory"}},s=[{value:"Configure hydra.mode (new in Hydra 1.2)",id:"configure-hydramode-new-in-hydra-12",children:[],level:3},{value:"--multirun (-m) from the command-line",id:"--multirun--m-from-the-command-line",children:[],level:3},{value:"Sweeping via hydra.sweeper.params",id:"sweeping-via-hydrasweeperparams",children:[],level:3},{value:"Additional sweep types",id:"additional-sweep-types",children:[],level:3},{value:"Sweeper",id:"sweeper",children:[],level:3},{value:"Launcher",id:"launcher",children:[],level:3}],u={toc:s};function c(e){var n=e.components,a=(0,r.A)(e,l);return(0,i.mdx)("wrapper",(0,t.A)({},u,a,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Sometimes you want to run the same application with multiple different configurations.",(0,i.mdx)("br",{parentName:"p"}),"\n","E.g. running a performance test on each of the databases with each of the schemas."),(0,i.mdx)("p",null,"You can multirun a Hydra application via either commandline or configuration:"),(0,i.mdx)("h3",{id:"configure-hydramode-new-in-hydra-12"},"Configure ",(0,i.mdx)("inlineCode",{parentName:"h3"},"hydra.mode")," (new in Hydra 1.2)"),(0,i.mdx)("p",null,"You can configure ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.mode")," in any supported way. The legal values are ",(0,i.mdx)("inlineCode",{parentName:"p"},"RUN")," and ",(0,i.mdx)("inlineCode",{parentName:"p"},"MULTIRUN"),".\nThe following shows how to override from the command-line and sweep over all combinations of the dbs and schemas.\nSetting ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.mode=MULTIRUN")," in your input config would make your application multi-run by default."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="$ python my_app.py hydra.mode=MULTIRUN db=mysql,postgresql schema=warehouse,support,school"',title:'"$',python:!0,"my_app.py":!0,"hydra.mode":"MULTIRUN",db:"mysql,postgresql",schema:'warehouse,support,school"'},"[2021-01-20 17:25:03,317][HYDRA] Launching 6 jobs locally\n[2021-01-20 17:25:03,318][HYDRA] #0 : db=mysql schema=warehouse\n[2021-01-20 17:25:03,458][HYDRA] #1 : db=mysql schema=support\n[2021-01-20 17:25:03,602][HYDRA] #2 : db=mysql schema=school\n[2021-01-20 17:25:03,755][HYDRA] #3 : db=postgresql schema=warehouse\n[2021-01-20 17:25:03,895][HYDRA] #4 : db=postgresql schema=support\n[2021-01-20 17:25:04,040][HYDRA] #5 : db=postgresql schema=school\n")),(0,i.mdx)("p",null,"The printed configurations have been omitted for brevity."),(0,i.mdx)("h3",{id:"--multirun--m-from-the-command-line"},(0,i.mdx)("inlineCode",{parentName:"h3"},"--multirun (-m)")," from the command-line"),(0,i.mdx)("p",null,"You can achieve the above from command-line as well:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"python my_app.py --multirun db=mysql,postgresql schema=warehouse,support,school\n")),(0,i.mdx)("p",null,"or "),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"python my_app.py -m db=mysql,postgresql schema=warehouse,support,school\n")),(0,i.mdx)("p",null,"You can access ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.mode")," at runtime to determine whether the application is in RUN or MULTIRUN mode. Check ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.2/configure_hydra/intro"},"here"),"\non how to access Hydra config at run time."),(0,i.mdx)("p",null,"If conflicts arise (e.g., ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.mode=RUN")," and the application was run with ",(0,i.mdx)("inlineCode",{parentName:"p"},"--multirun"),"), Hydra will determine the value of ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.mode"),"\nat run time. The following table shows what runtime ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.mode")," value you'd get with different input configs and commandline combinations."),(0,i.mdx)("table",null,(0,i.mdx)("thead",{parentName:"table"},(0,i.mdx)("tr",{parentName:"thead"},(0,i.mdx)("th",{parentName:"tr",align:null}),(0,i.mdx)("th",{parentName:"tr",align:null},"No multirun commandline flag"),(0,i.mdx)("th",{parentName:"tr",align:null},"--multirun ( -m)"))),(0,i.mdx)("tbody",{parentName:"table"},(0,i.mdx)("tr",{parentName:"tbody"},(0,i.mdx)("td",{parentName:"tr",align:null},"hydra.mode=RUN"),(0,i.mdx)("td",{parentName:"tr",align:null},"RunMode.RUN"),(0,i.mdx)("td",{parentName:"tr",align:null},"RunMode.MULTIRUN (with UserWarning)")),(0,i.mdx)("tr",{parentName:"tbody"},(0,i.mdx)("td",{parentName:"tr",align:null},"hydra.mode=MULTIRUN"),(0,i.mdx)("td",{parentName:"tr",align:null},"RunMode.MULTIRUN"),(0,i.mdx)("td",{parentName:"tr",align:null},"RunMode.MULTIRUN")),(0,i.mdx)("tr",{parentName:"tbody"},(0,i.mdx)("td",{parentName:"tr",align:null},"hydra.mode=None (default)"),(0,i.mdx)("td",{parentName:"tr",align:null},"RunMode.RUN"),(0,i.mdx)("td",{parentName:"tr",align:null},"RunMode.MULTIRUN")))),(0,i.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,i.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,i.mdx)("h5",{parentName:"div"},(0,i.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,i.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,i.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,i.mdx)("div",{parentName:"div",className:"admonition-content"},(0,i.mdx)("p",{parentName:"div"},"Hydra composes configs lazily at job launching time. If you change code or configs after launching a job/sweep, the final\ncomposed configs might be impacted."))),(0,i.mdx)("h3",{id:"sweeping-via-hydrasweeperparams"},"Sweeping via ",(0,i.mdx)("inlineCode",{parentName:"h3"},"hydra.sweeper.params")),(0,i.mdx)(o.C,{to:"examples/tutorials/basic/running_your_hydra_app/5_basic_sweep",mdxType:"ExampleGithubLink"}),(0,i.mdx)("p",null,"You can also define sweeping in the input configs by overriding\n",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.sweeper.params"),". Using the above example, the same multirun could be achieved via the following config."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml"},"hydra:\n sweeper:\n params:\n db: mysql,postgresql\n schema: warehouse,support,school\n")),(0,i.mdx)("p",null,"The syntax are consistent for both input configs and commandline overrides.\nIf a sweep is specified in both an input config and at the command line,\nthen the commandline sweep will take precedence over the sweep defined\nin the input config. If we run the same application with the above input config and a new commandline override:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="$ python my_app.py -m db=mysql"',title:'"$',python:!0,"my_app.py":!0,"-m":!0,db:'mysql"'},"[2021-01-20 17:25:03,317][HYDRA] Launching 3 jobs locally\n[2021-01-20 17:25:03,318][HYDRA] #0 : db=mysql schema=warehouse\n[2021-01-20 17:25:03,458][HYDRA] #1 : db=mysql schema=support\n[2021-01-20 17:25:03,602][HYDRA] #2 : db=mysql schema=school\n")),(0,i.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,i.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,i.mdx)("h5",{parentName:"div"},(0,i.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,i.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,i.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"info")),(0,i.mdx)("div",{parentName:"div",className:"admonition-content"},(0,i.mdx)("p",{parentName:"div"},"The above configuration methods only apply to Hydra's default ",(0,i.mdx)("inlineCode",{parentName:"p"},"BasicSweeper")," for now. For other sweepers, please check out the\ncorresponding documentations."))),(0,i.mdx)("h3",{id:"additional-sweep-types"},"Additional sweep types"),(0,i.mdx)("p",null,"Hydra supports other kinds of sweeps, e.g.:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python"},"x=range(1,10) # 1-9\nschema=glob(*) # warehouse,support,school\nschema=glob(*,exclude=w*) # support,school\n")),(0,i.mdx)("p",null,"See the ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.2/advanced/override_grammar/extended"},"Extended Override syntax")," for details."),(0,i.mdx)("h3",{id:"sweeper"},"Sweeper"),(0,i.mdx)("p",null,"The default sweeping logic is built into Hydra. Additional sweepers are available as plugins.\nFor example, the ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.2/plugins/ax_sweeper"},"Ax Sweeper")," can automatically find the best parameter combination!"),(0,i.mdx)("h3",{id:"launcher"},"Launcher"),(0,i.mdx)("p",null,"By default, Hydra runs your multi-run jobs locally and serially.\nOther launchers are available as plugins for launching in parallel and on different clusters. For example, the ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.2/plugins/joblib_launcher"},"JobLib Launcher"),"\ncan execute the different parameter combinations in parallel on your local machine using multi-processing."))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/28a7fcb4.c503f86d.js b/assets/js/28a7fcb4.c503f86d.js new file mode 100644 index 0000000000..96846730d8 --- /dev/null +++ b/assets/js/28a7fcb4.c503f86d.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[6138],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>m,MDXProvider:()=>u,mdx:()=>y,useMDXComponents:()=>s,withMDXComponents:()=>p});var t=a(96540);function r(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(r[a]=e[a]);return r}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(r[a]=e[a])}return r}var m=t.createContext({}),p=function(e){return function(n){var a=s(n.components);return t.createElement(e,i({},n,{components:a}))}},s=function(e){var n=t.useContext(m),a=n;return e&&(a="function"==typeof e?e(n):l(l({},n),e)),a},u=function(e){var n=s(e.components);return t.createElement(m.Provider,{value:n},e.children)},c={inlineCode:"code",wrapper:function(e){var n=e.children;return t.createElement(t.Fragment,{},n)}},h=t.forwardRef((function(e,n){var a=e.components,r=e.mdxType,i=e.originalType,o=e.parentName,m=d(e,["components","mdxType","originalType","parentName"]),p=s(a),u=r,h=p["".concat(o,".").concat(u)]||p[u]||c[u]||i;return a?t.createElement(h,l(l({ref:n},m),{},{components:a})):t.createElement(h,l({ref:n},m))}));function y(e,n){var a=arguments,r=n&&n.mdxType;if("string"==typeof e||r){var i=a.length,o=new Array(i);o[0]=h;var l={};for(var d in n)hasOwnProperty.call(n,d)&&(l[d]=n[d]);l.originalType=e,l.mdxType="string"==typeof e?e:r,o[1]=l;for(var m=2;m{a.d(n,{A:()=>d,C:()=>m});var t=a(58168),r=a(96540),i=a(75489),o=a(44586),l=a(74098);function d(e){return r.createElement(i.default,(0,t.A)({},e,{to:(n=e.to,d=(0,l.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(a=null==d?void 0:d.name)?a:"current"]+n),target:"_blank"}));var n,a,d}function m(e){var n,a=null!=(n=e.text)?n:"Example (Click Here)";return r.createElement(d,e,r.createElement("span",null,"\xa0"),r.createElement("img",{src:"https://img.shields.io/badge/-"+a+"-informational",alt:"Example (Click Here)"}))}},46417:(e,n,a)=>{a.r(n),a.d(n,{contentTitle:()=>m,default:()=>c,frontMatter:()=>d,metadata:()=>p,toc:()=>s});var t=a(58168),r=a(98587),i=(a(96540),a(15680)),o=a(49595),l=["components"],d={id:"multi-run",title:"Multi-run",sidebar_label:"Multi-run"},m=void 0,p={unversionedId:"tutorials/basic/running_your_app/multi-run",id:"version-1.2/tutorials/basic/running_your_app/multi-run",title:"Multi-run",description:"Sometimes you want to run the same application with multiple different configurations.",source:"@site/versioned_docs/version-1.2/tutorials/basic/running_your_app/2_multirun.md",sourceDirName:"tutorials/basic/running_your_app",slug:"/tutorials/basic/running_your_app/multi-run",permalink:"/docs/1.2/tutorials/basic/running_your_app/multi-run",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/tutorials/basic/running_your_app/2_multirun.md",tags:[],version:"1.2",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:2,frontMatter:{id:"multi-run",title:"Multi-run",sidebar_label:"Multi-run"},sidebar:"docs",previous:{title:"Putting it all together",permalink:"/docs/1.2/tutorials/basic/your_first_app/composition"},next:{title:"Output/Working directory",permalink:"/docs/1.2/tutorials/basic/running_your_app/working_directory"}},s=[{value:"Configure hydra.mode (new in Hydra 1.2)",id:"configure-hydramode-new-in-hydra-12",children:[],level:3},{value:"--multirun (-m) from the command-line",id:"--multirun--m-from-the-command-line",children:[],level:3},{value:"Sweeping via hydra.sweeper.params",id:"sweeping-via-hydrasweeperparams",children:[],level:3},{value:"Additional sweep types",id:"additional-sweep-types",children:[],level:3},{value:"Sweeper",id:"sweeper",children:[],level:3},{value:"Launcher",id:"launcher",children:[],level:3}],u={toc:s};function c(e){var n=e.components,a=(0,r.A)(e,l);return(0,i.mdx)("wrapper",(0,t.A)({},u,a,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Sometimes you want to run the same application with multiple different configurations.",(0,i.mdx)("br",{parentName:"p"}),"\n","E.g. running a performance test on each of the databases with each of the schemas."),(0,i.mdx)("p",null,"You can multirun a Hydra application via either commandline or configuration:"),(0,i.mdx)("h3",{id:"configure-hydramode-new-in-hydra-12"},"Configure ",(0,i.mdx)("inlineCode",{parentName:"h3"},"hydra.mode")," (new in Hydra 1.2)"),(0,i.mdx)("p",null,"You can configure ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.mode")," in any supported way. The legal values are ",(0,i.mdx)("inlineCode",{parentName:"p"},"RUN")," and ",(0,i.mdx)("inlineCode",{parentName:"p"},"MULTIRUN"),".\nThe following shows how to override from the command-line and sweep over all combinations of the dbs and schemas.\nSetting ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.mode=MULTIRUN")," in your input config would make your application multi-run by default."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="$ python my_app.py hydra.mode=MULTIRUN db=mysql,postgresql schema=warehouse,support,school"',title:'"$',python:!0,"my_app.py":!0,"hydra.mode":"MULTIRUN",db:"mysql,postgresql",schema:'warehouse,support,school"'},"[2021-01-20 17:25:03,317][HYDRA] Launching 6 jobs locally\n[2021-01-20 17:25:03,318][HYDRA] #0 : db=mysql schema=warehouse\n[2021-01-20 17:25:03,458][HYDRA] #1 : db=mysql schema=support\n[2021-01-20 17:25:03,602][HYDRA] #2 : db=mysql schema=school\n[2021-01-20 17:25:03,755][HYDRA] #3 : db=postgresql schema=warehouse\n[2021-01-20 17:25:03,895][HYDRA] #4 : db=postgresql schema=support\n[2021-01-20 17:25:04,040][HYDRA] #5 : db=postgresql schema=school\n")),(0,i.mdx)("p",null,"The printed configurations have been omitted for brevity."),(0,i.mdx)("h3",{id:"--multirun--m-from-the-command-line"},(0,i.mdx)("inlineCode",{parentName:"h3"},"--multirun (-m)")," from the command-line"),(0,i.mdx)("p",null,"You can achieve the above from command-line as well:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"python my_app.py --multirun db=mysql,postgresql schema=warehouse,support,school\n")),(0,i.mdx)("p",null,"or "),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"python my_app.py -m db=mysql,postgresql schema=warehouse,support,school\n")),(0,i.mdx)("p",null,"You can access ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.mode")," at runtime to determine whether the application is in RUN or MULTIRUN mode. Check ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.2/configure_hydra/intro"},"here"),"\non how to access Hydra config at run time."),(0,i.mdx)("p",null,"If conflicts arise (e.g., ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.mode=RUN")," and the application was run with ",(0,i.mdx)("inlineCode",{parentName:"p"},"--multirun"),"), Hydra will determine the value of ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.mode"),"\nat run time. The following table shows what runtime ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.mode")," value you'd get with different input configs and commandline combinations."),(0,i.mdx)("table",null,(0,i.mdx)("thead",{parentName:"table"},(0,i.mdx)("tr",{parentName:"thead"},(0,i.mdx)("th",{parentName:"tr",align:null}),(0,i.mdx)("th",{parentName:"tr",align:null},"No multirun commandline flag"),(0,i.mdx)("th",{parentName:"tr",align:null},"--multirun ( -m)"))),(0,i.mdx)("tbody",{parentName:"table"},(0,i.mdx)("tr",{parentName:"tbody"},(0,i.mdx)("td",{parentName:"tr",align:null},"hydra.mode=RUN"),(0,i.mdx)("td",{parentName:"tr",align:null},"RunMode.RUN"),(0,i.mdx)("td",{parentName:"tr",align:null},"RunMode.MULTIRUN (with UserWarning)")),(0,i.mdx)("tr",{parentName:"tbody"},(0,i.mdx)("td",{parentName:"tr",align:null},"hydra.mode=MULTIRUN"),(0,i.mdx)("td",{parentName:"tr",align:null},"RunMode.MULTIRUN"),(0,i.mdx)("td",{parentName:"tr",align:null},"RunMode.MULTIRUN")),(0,i.mdx)("tr",{parentName:"tbody"},(0,i.mdx)("td",{parentName:"tr",align:null},"hydra.mode=None (default)"),(0,i.mdx)("td",{parentName:"tr",align:null},"RunMode.RUN"),(0,i.mdx)("td",{parentName:"tr",align:null},"RunMode.MULTIRUN")))),(0,i.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,i.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,i.mdx)("h5",{parentName:"div"},(0,i.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,i.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,i.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,i.mdx)("div",{parentName:"div",className:"admonition-content"},(0,i.mdx)("p",{parentName:"div"},"Hydra composes configs lazily at job launching time. If you change code or configs after launching a job/sweep, the final\ncomposed configs might be impacted."))),(0,i.mdx)("h3",{id:"sweeping-via-hydrasweeperparams"},"Sweeping via ",(0,i.mdx)("inlineCode",{parentName:"h3"},"hydra.sweeper.params")),(0,i.mdx)(o.C,{to:"examples/tutorials/basic/running_your_hydra_app/5_basic_sweep",mdxType:"ExampleGithubLink"}),(0,i.mdx)("p",null,"You can also define sweeping in the input configs by overriding\n",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.sweeper.params"),". Using the above example, the same multirun could be achieved via the following config."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml"},"hydra:\n sweeper:\n params:\n db: mysql,postgresql\n schema: warehouse,support,school\n")),(0,i.mdx)("p",null,"The syntax are consistent for both input configs and commandline overrides.\nIf a sweep is specified in both an input config and at the command line,\nthen the commandline sweep will take precedence over the sweep defined\nin the input config. If we run the same application with the above input config and a new commandline override:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="$ python my_app.py -m db=mysql"',title:'"$',python:!0,"my_app.py":!0,"-m":!0,db:'mysql"'},"[2021-01-20 17:25:03,317][HYDRA] Launching 3 jobs locally\n[2021-01-20 17:25:03,318][HYDRA] #0 : db=mysql schema=warehouse\n[2021-01-20 17:25:03,458][HYDRA] #1 : db=mysql schema=support\n[2021-01-20 17:25:03,602][HYDRA] #2 : db=mysql schema=school\n")),(0,i.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,i.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,i.mdx)("h5",{parentName:"div"},(0,i.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,i.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,i.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"info")),(0,i.mdx)("div",{parentName:"div",className:"admonition-content"},(0,i.mdx)("p",{parentName:"div"},"The above configuration methods only apply to Hydra's default ",(0,i.mdx)("inlineCode",{parentName:"p"},"BasicSweeper")," for now. For other sweepers, please check out the\ncorresponding documentations."))),(0,i.mdx)("h3",{id:"additional-sweep-types"},"Additional sweep types"),(0,i.mdx)("p",null,"Hydra supports other kinds of sweeps, e.g.:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python"},"x=range(1,10) # 1-9\nschema=glob(*) # warehouse,support,school\nschema=glob(*,exclude=w*) # support,school\n")),(0,i.mdx)("p",null,"See the ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.2/advanced/override_grammar/extended"},"Extended Override syntax")," for details."),(0,i.mdx)("h3",{id:"sweeper"},"Sweeper"),(0,i.mdx)("p",null,"The default sweeping logic is built into Hydra. Additional sweepers are available as plugins.\nFor example, the ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.2/plugins/ax_sweeper"},"Ax Sweeper")," can automatically find the best parameter combination!"),(0,i.mdx)("h3",{id:"launcher"},"Launcher"),(0,i.mdx)("p",null,"By default, Hydra runs your multi-run jobs locally and serially.\nOther launchers are available as plugins for launching in parallel and on different clusters. For example, the ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.2/plugins/joblib_launcher"},"JobLib Launcher"),"\ncan execute the different parameter combinations in parallel on your local machine using multi-processing."))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/290e3655.a6cc60cf.js b/assets/js/290e3655.a6cc60cf.js new file mode 100644 index 0000000000..fa9aa943c2 --- /dev/null +++ b/assets/js/290e3655.a6cc60cf.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[1176],{15680:(e,r,t)=>{t.r(r),t.d(r,{MDXContext:()=>p,MDXProvider:()=>s,mdx:()=>g,useMDXComponents:()=>c,withMDXComponents:()=>l});var n=t(96540);function o(e,r,t){return r in e?Object.defineProperty(e,r,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[r]=t,e}function i(){return i=Object.assign||function(e){for(var r=1;r=0||(o[t]=e[t]);return o}(e,r);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(o[t]=e[t])}return o}var p=n.createContext({}),l=function(e){return function(r){var t=c(r.components);return n.createElement(e,i({},r,{components:t}))}},c=function(e){var r=n.useContext(p),t=r;return e&&(t="function"==typeof e?e(r):d(d({},r),e)),t},s=function(e){var r=c(e.components);return n.createElement(p.Provider,{value:r},e.children)},m={inlineCode:"code",wrapper:function(e){var r=e.children;return n.createElement(n.Fragment,{},r)}},y=n.forwardRef((function(e,r){var t=e.components,o=e.mdxType,i=e.originalType,a=e.parentName,p=u(e,["components","mdxType","originalType","parentName"]),l=c(t),s=o,y=l["".concat(a,".").concat(s)]||l[s]||m[s]||i;return t?n.createElement(y,d(d({ref:r},p),{},{components:t})):n.createElement(y,d({ref:r},p))}));function g(e,r){var t=arguments,o=r&&r.mdxType;if("string"==typeof e||o){var i=t.length,a=new Array(i);a[0]=y;var d={};for(var u in r)hasOwnProperty.call(r,u)&&(d[u]=r[u]);d.originalType=e,d.mdxType="string"==typeof e?e:o,a[1]=d;for(var p=2;p{t.d(r,{A:()=>u,C:()=>p});var n=t(58168),o=t(96540),i=t(75489),a=t(44586),d=t(74098);function u(e){return o.createElement(i.default,(0,n.A)({},e,{to:(r=e.to,u=(0,d.useActiveVersion)(),(0,a.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==u?void 0:u.name)?t:"current"]+r),target:"_blank"}));var r,t,u}function p(e){var r,t=null!=(r=e.text)?r:"Example (Click Here)";return o.createElement(u,e,o.createElement("span",null,"\xa0"),o.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},33766:(e,r,t)=>{t.r(r),t.d(r,{contentTitle:()=>p,default:()=>m,frontMatter:()=>u,metadata:()=>l,toc:()=>c});var n=t(58168),o=t(98587),i=(t(96540),t(15680)),a=t(49595),d=["components"],u={id:"working_directory",title:"Output/Working directory",sidebar_label:"Output/Working directory"},p=void 0,l={unversionedId:"tutorials/basic/running_your_app/working_directory",id:"tutorials/basic/running_your_app/working_directory",title:"Output/Working directory",description:"Hydra can solve the problem of your needing to specify a new output directory for each run, by",source:"@site/docs/tutorials/basic/running_your_app/3_working_directory.md",sourceDirName:"tutorials/basic/running_your_app",slug:"/tutorials/basic/running_your_app/working_directory",permalink:"/docs/tutorials/basic/running_your_app/working_directory",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/tutorials/basic/running_your_app/3_working_directory.md",tags:[],version:"current",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:3,frontMatter:{id:"working_directory",title:"Output/Working directory",sidebar_label:"Output/Working directory"},sidebar:"docs",previous:{title:"Multi-run",permalink:"/docs/tutorials/basic/running_your_app/multi-run"},next:{title:"Logging",permalink:"/docs/tutorials/basic/running_your_app/logging"}},c=[{value:"Automatically change current working dir to job's output dir",id:"automatically-change-current-working-dir-to-jobs-output-dir",children:[],level:3},{value:"Changing or disabling Hydra's output subdir",id:"changing-or-disabling-hydras-output-subdir",children:[],level:3},{value:"Accessing the original working directory in your application",id:"accessing-the-original-working-directory-in-your-application",children:[],level:3}],s={toc:c};function m(e){var r=e.components,t=(0,o.A)(e,d);return(0,i.mdx)("wrapper",(0,n.A)({},s,t,{components:r,mdxType:"MDXLayout"}),(0,i.mdx)(a.C,{to:"examples/tutorials/basic/running_your_hydra_app/3_working_directory",mdxType:"ExampleGithubLink"}),(0,i.mdx)("p",null,"Hydra can solve the problem of your needing to specify a new output directory for each run, by\ncreating a directory for each run and executing your code within that output directory.\nBy default, this output directory is used to store Hydra output for the run (Configuration, Logs etc)."),(0,i.mdx)("p",null,"Every time you run the app, a new output directory is created.\nYou can retrieve the path of the output directy by\n",(0,i.mdx)("a",{parentName:"p",href:"/docs/configure_hydra/intro#accessing-the-hydra-config"},"inspecting the Hydra config")," as in the example below."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app.py"',title:'"my_app.py"'},'import os\nfrom omegaconf import DictConfig\nimport hydra\n\n@hydra.main(version_base=None)\ndef my_app(_cfg: DictConfig) -> None:\n print(f"Working directory : {os.getcwd()}")\n print(f"Output directory : {hydra.core.hydra_config.HydraConfig.get().runtime.output_dir}")\n')),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text"},"$ python my_app.py\nWorking directory : /home/omry/dev/hydra\nOutput directory : /home/omry/dev/hydra/outputs/2019-09-25/15-16-17\n\n$ python my_app.py\nWorking directory : /home/omry/dev/hydra\nOutput directory : /home/omry/dev/hydra/outputs/2019-09-25/15-16-19\n")),(0,i.mdx)("p",null,"Let's take a look at one of the output directories:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text"},"$ tree outputs/2019-09-25/15-16-17\noutputs/2019-09-25/15-16-17\n\u251c\u2500\u2500 .hydra\n\u2502 \u251c\u2500\u2500 config.yaml\n\u2502 \u251c\u2500\u2500 hydra.yaml\n\u2502 \u2514\u2500\u2500 overrides.yaml\n\u2514\u2500\u2500 my_app.log\n")),(0,i.mdx)("p",null,"We have the Hydra output directory (",(0,i.mdx)("inlineCode",{parentName:"p"},".hydra")," by default), and the application log file.\nInside the Hydra output directory we have:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"config.yaml"),": A dump of the user specified configuration"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"hydra.yaml"),": A dump of the Hydra configuration"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"overrides.yaml"),": The command line overrides used")),(0,i.mdx)("p",null,"And in the main output directory:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"my_app.log"),": A log file created for this run")),(0,i.mdx)("p",null,"You can configure the name of the output directory using\nthe ",(0,i.mdx)("a",{parentName:"p",href:"/docs/configure_hydra/workdir"},"customizing the working directory")," pattern."),(0,i.mdx)("h3",{id:"automatically-change-current-working-dir-to-jobs-output-dir"},"Automatically change current working dir to job's output dir"),(0,i.mdx)("p",null,"By setting ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir=True"),", you can configure\nHydra's ",(0,i.mdx)("inlineCode",{parentName:"p"},"@hydra.main")," decorator to change python's working directory by calling\n",(0,i.mdx)("inlineCode",{parentName:"p"},"os.chdir")," before passing control to the user's decorated main function.\nAs of Hydra v1.2, ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir")," defaults to ",(0,i.mdx)("inlineCode",{parentName:"p"},"False"),".\nSetting ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir=True")," enables convenient use of the output directory to\nstore output for the application (For example, a database dump file)."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-bash"},"# check current working dir\n$ pwd\n/home/jasha/dev/hydra\n\n# for Hydra >= 1.2, working dir remains unchanged by default\n$ python my_app.py\nWorking directory : /home/jasha/dev/hydra\nOutput directory : /home/jasha/dev/hydra/outputs/2023-04-18/13-43-24\n\n# working dir changed to output dir\n$ python my_app.py hydra.job.chdir=True\nWorking directory : /home/jasha/dev/hydra/outputs/2023-04-18/13-43-17\nOutput directory : /home/jasha/dev/hydra/outputs/2023-04-18/13-43-17\n\n# output dir and files are still created even if `chdir` is disabled:\n$ tree -a outputs/2023-04-18/13-43-24/\noutputs/2023-04-18/13-43-24/\n\u251c\u2500\u2500 .hydra\n\u2502\xa0\xa0 \u251c\u2500\u2500 config.yaml\n\u2502\xa0\xa0 \u251c\u2500\u2500 hydra.yaml\n\u2502\xa0\xa0 \u2514\u2500\u2500 overrides.yaml\n\u2514\u2500\u2500 my_app.log\n")),(0,i.mdx)("h3",{id:"changing-or-disabling-hydras-output-subdir"},"Changing or disabling Hydra's output subdir"),(0,i.mdx)("p",null,"You can change the ",(0,i.mdx)("inlineCode",{parentName:"p"},".hydra")," subdirectory name by overriding ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.output_subdir"),".\nYou can disable its creation by overriding ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.output_subdir")," to ",(0,i.mdx)("inlineCode",{parentName:"p"},"null"),"."),(0,i.mdx)("h3",{id:"accessing-the-original-working-directory-in-your-application"},"Accessing the original working directory in your application"),(0,i.mdx)("p",null,"With ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir=True"),", you can still access the original working directory by importing ",(0,i.mdx)("inlineCode",{parentName:"p"},"get_original_cwd()")," and ",(0,i.mdx)("inlineCode",{parentName:"p"},"to_absolute_path()")," in ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.utils"),":"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python"},'from hydra.utils import get_original_cwd, to_absolute_path\n\n@hydra.main(version_base=None)\ndef my_app(_cfg: DictConfig) -> None:\n print(f"Current working directory : {os.getcwd()}")\n print(f"Orig working directory : {get_original_cwd()}")\n print(f"to_absolute_path(\'foo\') : {to_absolute_path(\'foo\')}")\n print(f"to_absolute_path(\'/foo\') : {to_absolute_path(\'/foo\')}")\n\nif __name__ == "__main__":\n my_app()\n')),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="$ python examples/tutorial/8_working_directory/original_cwd.py"',title:'"$',python:!0,'examples/tutorial/8_working_directory/original_cwd.py"':!0},"Current working directory : /Users/omry/dev/hydra/outputs/2019-10-23/10-53-03\nOriginal working directory : /Users/omry/dev/hydra\nto_absolute_path('foo') : /Users/omry/dev/hydra/foo\nto_absolute_path('/foo') : /foo\n")),(0,i.mdx)("p",null,"The name of the generated working directories can be ",(0,i.mdx)("a",{parentName:"p",href:"/docs/configure_hydra/workdir"},"customized"),"."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/290e3655.f5775373.js b/assets/js/290e3655.f5775373.js deleted file mode 100644 index 6108a02628..0000000000 --- a/assets/js/290e3655.f5775373.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[1176],{15680:(e,r,t)=>{t.r(r),t.d(r,{MDXContext:()=>p,MDXProvider:()=>s,mdx:()=>g,useMDXComponents:()=>c,withMDXComponents:()=>l});var n=t(96540);function o(e,r,t){return r in e?Object.defineProperty(e,r,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[r]=t,e}function i(){return i=Object.assign||function(e){for(var r=1;r=0||(o[t]=e[t]);return o}(e,r);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(o[t]=e[t])}return o}var p=n.createContext({}),l=function(e){return function(r){var t=c(r.components);return n.createElement(e,i({},r,{components:t}))}},c=function(e){var r=n.useContext(p),t=r;return e&&(t="function"==typeof e?e(r):d(d({},r),e)),t},s=function(e){var r=c(e.components);return n.createElement(p.Provider,{value:r},e.children)},m={inlineCode:"code",wrapper:function(e){var r=e.children;return n.createElement(n.Fragment,{},r)}},y=n.forwardRef((function(e,r){var t=e.components,o=e.mdxType,i=e.originalType,a=e.parentName,p=u(e,["components","mdxType","originalType","parentName"]),l=c(t),s=o,y=l["".concat(a,".").concat(s)]||l[s]||m[s]||i;return t?n.createElement(y,d(d({ref:r},p),{},{components:t})):n.createElement(y,d({ref:r},p))}));function g(e,r){var t=arguments,o=r&&r.mdxType;if("string"==typeof e||o){var i=t.length,a=new Array(i);a[0]=y;var d={};for(var u in r)hasOwnProperty.call(r,u)&&(d[u]=r[u]);d.originalType=e,d.mdxType="string"==typeof e?e:o,a[1]=d;for(var p=2;p{t.d(r,{A:()=>u,C:()=>p});var n=t(58168),o=t(96540),i=t(75489),a=t(44586),d=t(74098);function u(e){return o.createElement(i.default,(0,n.A)({},e,{to:(r=e.to,u=(0,d.useActiveVersion)(),(0,a.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==u?void 0:u.name)?t:"current"]+r),target:"_blank"}));var r,t,u}function p(e){var r,t=null!=(r=e.text)?r:"Example (Click Here)";return o.createElement(u,e,o.createElement("span",null,"\xa0"),o.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},33766:(e,r,t)=>{t.r(r),t.d(r,{contentTitle:()=>p,default:()=>m,frontMatter:()=>u,metadata:()=>l,toc:()=>c});var n=t(58168),o=t(98587),i=(t(96540),t(15680)),a=t(49595),d=["components"],u={id:"working_directory",title:"Output/Working directory",sidebar_label:"Output/Working directory"},p=void 0,l={unversionedId:"tutorials/basic/running_your_app/working_directory",id:"tutorials/basic/running_your_app/working_directory",title:"Output/Working directory",description:"Hydra can solve the problem of your needing to specify a new output directory for each run, by",source:"@site/docs/tutorials/basic/running_your_app/3_working_directory.md",sourceDirName:"tutorials/basic/running_your_app",slug:"/tutorials/basic/running_your_app/working_directory",permalink:"/docs/tutorials/basic/running_your_app/working_directory",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/tutorials/basic/running_your_app/3_working_directory.md",tags:[],version:"current",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:3,frontMatter:{id:"working_directory",title:"Output/Working directory",sidebar_label:"Output/Working directory"},sidebar:"docs",previous:{title:"Multi-run",permalink:"/docs/tutorials/basic/running_your_app/multi-run"},next:{title:"Logging",permalink:"/docs/tutorials/basic/running_your_app/logging"}},c=[{value:"Automatically change current working dir to job's output dir",id:"automatically-change-current-working-dir-to-jobs-output-dir",children:[],level:3},{value:"Changing or disabling Hydra's output subdir",id:"changing-or-disabling-hydras-output-subdir",children:[],level:3},{value:"Accessing the original working directory in your application",id:"accessing-the-original-working-directory-in-your-application",children:[],level:3}],s={toc:c};function m(e){var r=e.components,t=(0,o.A)(e,d);return(0,i.mdx)("wrapper",(0,n.A)({},s,t,{components:r,mdxType:"MDXLayout"}),(0,i.mdx)(a.C,{to:"examples/tutorials/basic/running_your_hydra_app/3_working_directory",mdxType:"ExampleGithubLink"}),(0,i.mdx)("p",null,"Hydra can solve the problem of your needing to specify a new output directory for each run, by\ncreating a directory for each run and executing your code within that output directory.\nBy default, this output directory is used to store Hydra output for the run (Configuration, Logs etc)."),(0,i.mdx)("p",null,"Every time you run the app, a new output directory is created.\nYou can retrieve the path of the output directy by\n",(0,i.mdx)("a",{parentName:"p",href:"/docs/configure_hydra/intro#accessing-the-hydra-config"},"inspecting the Hydra config")," as in the example below."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app.py"',title:'"my_app.py"'},'import os\nfrom omegaconf import DictConfig\nimport hydra\n\n@hydra.main(version_base=None)\ndef my_app(_cfg: DictConfig) -> None:\n print(f"Working directory : {os.getcwd()}")\n print(f"Output directory : {hydra.core.hydra_config.HydraConfig.get().runtime.output_dir}")\n')),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text"},"$ python my_app.py\nWorking directory : /home/omry/dev/hydra\nOutput directory : /home/omry/dev/hydra/outputs/2019-09-25/15-16-17\n\n$ python my_app.py\nWorking directory : /home/omry/dev/hydra\nOutput directory : /home/omry/dev/hydra/outputs/2019-09-25/15-16-19\n")),(0,i.mdx)("p",null,"Let's take a look at one of the output directories:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text"},"$ tree outputs/2019-09-25/15-16-17\noutputs/2019-09-25/15-16-17\n\u251c\u2500\u2500 .hydra\n\u2502 \u251c\u2500\u2500 config.yaml\n\u2502 \u251c\u2500\u2500 hydra.yaml\n\u2502 \u2514\u2500\u2500 overrides.yaml\n\u2514\u2500\u2500 my_app.log\n")),(0,i.mdx)("p",null,"We have the Hydra output directory (",(0,i.mdx)("inlineCode",{parentName:"p"},".hydra")," by default), and the application log file.\nInside the Hydra output directory we have:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"config.yaml"),": A dump of the user specified configuration"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"hydra.yaml"),": A dump of the Hydra configuration"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"overrides.yaml"),": The command line overrides used")),(0,i.mdx)("p",null,"And in the main output directory:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"my_app.log"),": A log file created for this run")),(0,i.mdx)("p",null,"You can configure the name of the output directory using\nthe ",(0,i.mdx)("a",{parentName:"p",href:"/docs/configure_hydra/workdir"},"customizing the working directory")," pattern."),(0,i.mdx)("h3",{id:"automatically-change-current-working-dir-to-jobs-output-dir"},"Automatically change current working dir to job's output dir"),(0,i.mdx)("p",null,"By setting ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir=True"),", you can configure\nHydra's ",(0,i.mdx)("inlineCode",{parentName:"p"},"@hydra.main")," decorator to change python's working directory by calling\n",(0,i.mdx)("inlineCode",{parentName:"p"},"os.chdir")," before passing control to the user's decorated main function.\nAs of Hydra v1.2, ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir")," defaults to ",(0,i.mdx)("inlineCode",{parentName:"p"},"False"),".\nSetting ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir=True")," enables convenient use of the output directory to\nstore output for the application (For example, a database dump file)."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-bash"},"# check current working dir\n$ pwd\n/home/jasha/dev/hydra\n\n# for Hydra >= 1.2, working dir remains unchanged by default\n$ python my_app.py\nWorking directory : /home/jasha/dev/hydra\nOutput directory : /home/jasha/dev/hydra/outputs/2023-04-18/13-43-24\n\n# working dir changed to output dir\n$ python my_app.py hydra.job.chdir=True\nWorking directory : /home/jasha/dev/hydra/outputs/2023-04-18/13-43-17\nOutput directory : /home/jasha/dev/hydra/outputs/2023-04-18/13-43-17\n\n# output dir and files are still created even if `chdir` is disabled:\n$ tree -a outputs/2023-04-18/13-43-24/\noutputs/2023-04-18/13-43-24/\n\u251c\u2500\u2500 .hydra\n\u2502\xa0\xa0 \u251c\u2500\u2500 config.yaml\n\u2502\xa0\xa0 \u251c\u2500\u2500 hydra.yaml\n\u2502\xa0\xa0 \u2514\u2500\u2500 overrides.yaml\n\u2514\u2500\u2500 my_app.log\n")),(0,i.mdx)("h3",{id:"changing-or-disabling-hydras-output-subdir"},"Changing or disabling Hydra's output subdir"),(0,i.mdx)("p",null,"You can change the ",(0,i.mdx)("inlineCode",{parentName:"p"},".hydra")," subdirectory name by overriding ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.output_subdir"),".\nYou can disable its creation by overriding ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.output_subdir")," to ",(0,i.mdx)("inlineCode",{parentName:"p"},"null"),"."),(0,i.mdx)("h3",{id:"accessing-the-original-working-directory-in-your-application"},"Accessing the original working directory in your application"),(0,i.mdx)("p",null,"With ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.job.chdir=True"),", you can still access the original working directory by importing ",(0,i.mdx)("inlineCode",{parentName:"p"},"get_original_cwd()")," and ",(0,i.mdx)("inlineCode",{parentName:"p"},"to_absolute_path()")," in ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.utils"),":"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python"},'from hydra.utils import get_original_cwd, to_absolute_path\n\n@hydra.main(version_base=None)\ndef my_app(_cfg: DictConfig) -> None:\n print(f"Current working directory : {os.getcwd()}")\n print(f"Orig working directory : {get_original_cwd()}")\n print(f"to_absolute_path(\'foo\') : {to_absolute_path(\'foo\')}")\n print(f"to_absolute_path(\'/foo\') : {to_absolute_path(\'/foo\')}")\n\nif __name__ == "__main__":\n my_app()\n')),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="$ python examples/tutorial/8_working_directory/original_cwd.py"',title:'"$',python:!0,'examples/tutorial/8_working_directory/original_cwd.py"':!0},"Current working directory : /Users/omry/dev/hydra/outputs/2019-10-23/10-53-03\nOriginal working directory : /Users/omry/dev/hydra\nto_absolute_path('foo') : /Users/omry/dev/hydra/foo\nto_absolute_path('/foo') : /foo\n")),(0,i.mdx)("p",null,"The name of the generated working directories can be ",(0,i.mdx)("a",{parentName:"p",href:"/docs/configure_hydra/workdir"},"customized"),"."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2c2e4037.67f033df.js b/assets/js/2c2e4037.67f033df.js deleted file mode 100644 index cd03278f78..0000000000 --- a/assets/js/2c2e4037.67f033df.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[6495],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>l,MDXProvider:()=>u,mdx:()=>f,useMDXComponents:()=>p,withMDXComponents:()=>d});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var l=r.createContext({}),d=function(e){return function(t){var n=p(t.components);return r.createElement(e,a({},t,{components:n}))}},p=function(e){var t=r.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):s(s({},t),e)),n},u=function(e){var t=p(e.components);return r.createElement(l.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},h=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,l=c(e,["components","mdxType","originalType","parentName"]),d=p(n),u=o,h=d["".concat(i,".").concat(u)]||d[u]||m[u]||a;return n?r.createElement(h,s(s({ref:t},l),{},{components:n})):r.createElement(h,s({ref:t},l))}));function f(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=n.length,i=new Array(a);i[0]=h;var s={};for(var c in t)hasOwnProperty.call(t,c)&&(s[c]=t[c]);s.originalType=e,s.mdxType="string"==typeof e?e:o,i[1]=s;for(var l=2;l{n.r(t),n.d(t,{contentTitle:()=>c,default:()=>u,frontMatter:()=>s,metadata:()=>l,toc:()=>d});var r=n(58168),o=n(98587),a=(n(96540),n(15680)),i=["components"],s={id:"intro",title:"Hydra at Facebook"},c=void 0,l={unversionedId:"fb/intro",id:"fb/intro",title:"Hydra at Facebook",description:"Intro",source:"@site/docs/fb/intro.md",sourceDirName:"fb",slug:"/fb/intro",permalink:"/docs/fb/intro",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/fb/intro.md",tags:[],version:"current",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"intro",title:"Hydra at Facebook"}},d=[{value:"Intro",id:"intro",children:[],level:3},{value:"Release strategy",id:"release-strategy",children:[],level:3},{value:"Maintaining this documentation",id:"maintaining-this-documentation",children:[],level:3}],p={toc:d};function u(e){var t=e.components,n=(0,o.A)(e,i);return(0,a.mdx)("wrapper",(0,r.A)({},p,n,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)("h3",{id:"intro"},"Intro"),(0,a.mdx)("p",null,"Facebook has multiple different environments, such as the ",(0,a.mdx)("strong",{parentName:"p"},"Internal FB Cluster"),", the ",(0,a.mdx)("strong",{parentName:"p"},"FAIR Cluster")," etc."),(0,a.mdx)("p",null,"The FB specific docs are describing the differences."),(0,a.mdx)("h3",{id:"release-strategy"},"Release strategy"),(0,a.mdx)("p",null,"Hydra's source of truth is the ",(0,a.mdx)("a",{parentName:"p",href:"https://github.com/facebookresearch/hydra"},"GitHub repo"),"."),(0,a.mdx)("p",null,"Hydra is developed using release branches. Once a new major is released, it is maintained in patch only mode.\nPrimary development is happening on the ",(0,a.mdx)("inlineCode",{parentName:"p"},"master")," branch."),(0,a.mdx)("p",null,"When a new major version of Hydra is released, a new release branch is created in Hydra repo. A corresponding Hydra version will be created inside ",(0,a.mdx)("inlineCode",{parentName:"p"},"github/facebookresearch/hydra_VERSION")," to track\nthe release branch."),(0,a.mdx)("p",null,"Hydra is trying hard to remain backward compatible between two subsequent versions and in most cases the upgrade will be smooth.\nThere could be some new deprecations warnings that should be fixed before the next major version."),(0,a.mdx)("h3",{id:"maintaining-this-documentation"},"Maintaining this documentation"),(0,a.mdx)("p",null,"This documentation lives in in the Hydra repo which is publicly accessible. The pages will only normally render on the internal\ncopy of the docs, but keep in mind that everyone can read those docs in the repo if they want to."),(0,a.mdx)("ol",null,(0,a.mdx)("li",{parentName:"ol"},"Do not put anything sensitive here, no root passwords or launch codes."),(0,a.mdx)("li",{parentName:"ol"},"If you are in need to have sensitive Hydra related documentation please reach out to the maintainers of Hydra for help.")))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2c2e4037.7c432b89.js b/assets/js/2c2e4037.7c432b89.js new file mode 100644 index 0000000000..5c71fc66ea --- /dev/null +++ b/assets/js/2c2e4037.7c432b89.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[6495],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>l,MDXProvider:()=>u,mdx:()=>f,useMDXComponents:()=>p,withMDXComponents:()=>d});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var l=r.createContext({}),d=function(e){return function(t){var n=p(t.components);return r.createElement(e,a({},t,{components:n}))}},p=function(e){var t=r.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):s(s({},t),e)),n},u=function(e){var t=p(e.components);return r.createElement(l.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},h=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,l=c(e,["components","mdxType","originalType","parentName"]),d=p(n),u=o,h=d["".concat(i,".").concat(u)]||d[u]||m[u]||a;return n?r.createElement(h,s(s({ref:t},l),{},{components:n})):r.createElement(h,s({ref:t},l))}));function f(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=n.length,i=new Array(a);i[0]=h;var s={};for(var c in t)hasOwnProperty.call(t,c)&&(s[c]=t[c]);s.originalType=e,s.mdxType="string"==typeof e?e:o,i[1]=s;for(var l=2;l{n.r(t),n.d(t,{contentTitle:()=>c,default:()=>u,frontMatter:()=>s,metadata:()=>l,toc:()=>d});var r=n(58168),o=n(98587),a=(n(96540),n(15680)),i=["components"],s={id:"intro",title:"Hydra at Facebook"},c=void 0,l={unversionedId:"fb/intro",id:"fb/intro",title:"Hydra at Facebook",description:"Intro",source:"@site/docs/fb/intro.md",sourceDirName:"fb",slug:"/fb/intro",permalink:"/docs/fb/intro",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/fb/intro.md",tags:[],version:"current",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"intro",title:"Hydra at Facebook"}},d=[{value:"Intro",id:"intro",children:[],level:3},{value:"Release strategy",id:"release-strategy",children:[],level:3},{value:"Maintaining this documentation",id:"maintaining-this-documentation",children:[],level:3}],p={toc:d};function u(e){var t=e.components,n=(0,o.A)(e,i);return(0,a.mdx)("wrapper",(0,r.A)({},p,n,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)("h3",{id:"intro"},"Intro"),(0,a.mdx)("p",null,"Facebook has multiple different environments, such as the ",(0,a.mdx)("strong",{parentName:"p"},"Internal FB Cluster"),", the ",(0,a.mdx)("strong",{parentName:"p"},"FAIR Cluster")," etc."),(0,a.mdx)("p",null,"The FB specific docs are describing the differences."),(0,a.mdx)("h3",{id:"release-strategy"},"Release strategy"),(0,a.mdx)("p",null,"Hydra's source of truth is the ",(0,a.mdx)("a",{parentName:"p",href:"https://github.com/facebookresearch/hydra"},"GitHub repo"),"."),(0,a.mdx)("p",null,"Hydra is developed using release branches. Once a new major is released, it is maintained in patch only mode.\nPrimary development is happening on the ",(0,a.mdx)("inlineCode",{parentName:"p"},"master")," branch."),(0,a.mdx)("p",null,"When a new major version of Hydra is released, a new release branch is created in Hydra repo. A corresponding Hydra version will be created inside ",(0,a.mdx)("inlineCode",{parentName:"p"},"github/facebookresearch/hydra_VERSION")," to track\nthe release branch."),(0,a.mdx)("p",null,"Hydra is trying hard to remain backward compatible between two subsequent versions and in most cases the upgrade will be smooth.\nThere could be some new deprecations warnings that should be fixed before the next major version."),(0,a.mdx)("h3",{id:"maintaining-this-documentation"},"Maintaining this documentation"),(0,a.mdx)("p",null,"This documentation lives in in the Hydra repo which is publicly accessible. The pages will only normally render on the internal\ncopy of the docs, but keep in mind that everyone can read those docs in the repo if they want to."),(0,a.mdx)("ol",null,(0,a.mdx)("li",{parentName:"ol"},"Do not put anything sensitive here, no root passwords or launch codes."),(0,a.mdx)("li",{parentName:"ol"},"If you are in need to have sensitive Hydra related documentation please reach out to the maintainers of Hydra for help.")))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2c8fa177.141fbc7e.js b/assets/js/2c8fa177.141fbc7e.js deleted file mode 100644 index 5d74e41c07..0000000000 --- a/assets/js/2c8fa177.141fbc7e.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[9980],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>l,MDXProvider:()=>u,mdx:()=>g,useMDXComponents:()=>p,withMDXComponents:()=>d});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var l=r.createContext({}),d=function(e){return function(t){var n=p(t.components);return r.createElement(e,a({},t,{components:n}))}},p=function(e){var t=r.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):s(s({},t),e)),n},u=function(e){var t=p(e.components);return r.createElement(l.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},f=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,l=c(e,["components","mdxType","originalType","parentName"]),d=p(n),u=o,f=d["".concat(i,".").concat(u)]||d[u]||m[u]||a;return n?r.createElement(f,s(s({ref:t},l),{},{components:n})):r.createElement(f,s({ref:t},l))}));function g(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=n.length,i=new Array(a);i[0]=f;var s={};for(var c in t)hasOwnProperty.call(t,c)&&(s[c]=t[c]);s.originalType=e,s.mdxType="string"==typeof e?e:o,i[1]=s;for(var l=2;l{n.d(t,{A:()=>c,C:()=>l});var r=n(58168),o=n(96540),a=n(75489),i=n(44586),s=n(74098);function c(e){return o.createElement(a.default,(0,r.A)({},e,{to:(t=e.to,c=(0,s.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==c?void 0:c.name)?n:"current"]+t),target:"_blank"}));var t,n,c}function l(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return o.createElement(c,e,o.createElement("span",null,"\xa0"),o.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},56021:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>l,default:()=>m,frontMatter:()=>c,metadata:()=>d,toc:()=>p});var r=n(58168),o=n(98587),a=(n(96540),n(15680)),i=n(49595),s=["components"],c={id:"structured_config",title:"Structured Configs example",sidebar_label:"Structured Configs example"},l=void 0,d={unversionedId:"advanced/instantiate_objects/structured_config",id:"version-1.2/advanced/instantiate_objects/structured_config",title:"Structured Configs example",description:"This example demonstrates the use of Structured Configs to instantiated objects.",source:"@site/versioned_docs/version-1.2/advanced/instantiate_objects/structured_config.md",sourceDirName:"advanced/instantiate_objects",slug:"/advanced/instantiate_objects/structured_config",permalink:"/docs/1.2/advanced/instantiate_objects/structured_config",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/advanced/instantiate_objects/structured_config.md",tags:[],version:"1.2",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"structured_config",title:"Structured Configs example",sidebar_label:"Structured Configs example"},sidebar:"docs",previous:{title:"Config files example",permalink:"/docs/1.2/advanced/instantiate_objects/config_files"},next:{title:"Compose API",permalink:"/docs/1.2/advanced/compose_api"}},p=[{value:"Example usage",id:"example-usage",children:[],level:4},{value:"Sample Output",id:"sample-output",children:[],level:4}],u={toc:p};function m(e){var t=e.components,n=(0,o.A)(e,s);return(0,a.mdx)("wrapper",(0,r.A)({},u,n,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)(i.C,{text:"Example applications",to:"examples/instantiate",mdxType:"ExampleGithubLink"}),(0,a.mdx)("p",null,"This example demonstrates the use of Structured Configs to instantiated objects."),(0,a.mdx)("h4",{id:"example-usage"},"Example usage"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app.py"',title:'"my_app.py"'},'class DBConnection:\n def __init__(self, driver: str, host: str, port: int) -> None:\n self.driver = driver\n self.host = host\n self.port = port\n\n def connect(self) -> None:\n print(f"{self.driver} connecting to {self.host}")\n\nclass MySQLConnection(DBConnection):\n def __init__(self, driver: str, host: str, port: int) -> None:\n super().__init__(driver=driver, host=host, port=port)\n\nclass PostgreSQLConnection(DBConnection):\n def __init__(self, driver: str, host: str, port: int, timeout: int) -> None:\n super().__init__(driver=driver, host=host, port=port)\n self.timeout = timeout\n\n@dataclass\nclass DBConfig:\n driver: str = MISSING\n host: str = "localhost"\n port: int = 80\n\n@dataclass\nclass MySQLConfig(DBConfig):\n _target_: str = "my_app.MySQLConnection"\n driver: str = "MySQL"\n port: int = 1234\n\n@dataclass\nclass PostGreSQLConfig(DBConfig):\n _target_: str = "my_app.PostgreSQLConnection"\n driver: str = "PostgreSQL"\n port: int = 5678\n timeout: int = 10\n\n@dataclass\nclass Config:\n defaults: List[Any] = field(default_factory=lambda: [{"db": "mysql"}])\n db: DBConfig = MISSING\n\n\ncs = ConfigStore.instance()\ncs.store(name="config", node=Config)\ncs.store(group="db", name="mysql", node=MySQLConfig)\ncs.store(group="db", name="postgresql", node=PostGreSQLConfig)\n\n@hydra.main(version_base=None, config_name="config")\ndef my_app(cfg: Config) -> None:\n connection = instantiate(cfg.db)\n connection.connect()\n\nif __name__ == "__main__":\n my_app()\n')),(0,a.mdx)("h4",{id:"sample-output"},"Sample Output"),(0,a.mdx)("div",{className:"row"},(0,a.mdx)("div",{className:"col col--6"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-bash"},"$ python my_app.py\nMySQL connecting to localhost:1234\n"))),(0,a.mdx)("div",{className:"col col--6"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-bash"},"$ python my_app.py db=postgresql\nPostgreSQL connecting to localhost:5678\n")))))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2c8fa177.7441b14e.js b/assets/js/2c8fa177.7441b14e.js new file mode 100644 index 0000000000..b89e7dafbf --- /dev/null +++ b/assets/js/2c8fa177.7441b14e.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[9980],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>l,MDXProvider:()=>u,mdx:()=>g,useMDXComponents:()=>p,withMDXComponents:()=>d});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var l=r.createContext({}),d=function(e){return function(t){var n=p(t.components);return r.createElement(e,a({},t,{components:n}))}},p=function(e){var t=r.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):s(s({},t),e)),n},u=function(e){var t=p(e.components);return r.createElement(l.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},f=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,l=c(e,["components","mdxType","originalType","parentName"]),d=p(n),u=o,f=d["".concat(i,".").concat(u)]||d[u]||m[u]||a;return n?r.createElement(f,s(s({ref:t},l),{},{components:n})):r.createElement(f,s({ref:t},l))}));function g(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=n.length,i=new Array(a);i[0]=f;var s={};for(var c in t)hasOwnProperty.call(t,c)&&(s[c]=t[c]);s.originalType=e,s.mdxType="string"==typeof e?e:o,i[1]=s;for(var l=2;l{n.d(t,{A:()=>c,C:()=>l});var r=n(58168),o=n(96540),a=n(75489),i=n(44586),s=n(74098);function c(e){return o.createElement(a.default,(0,r.A)({},e,{to:(t=e.to,c=(0,s.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==c?void 0:c.name)?n:"current"]+t),target:"_blank"}));var t,n,c}function l(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return o.createElement(c,e,o.createElement("span",null,"\xa0"),o.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},56021:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>l,default:()=>m,frontMatter:()=>c,metadata:()=>d,toc:()=>p});var r=n(58168),o=n(98587),a=(n(96540),n(15680)),i=n(49595),s=["components"],c={id:"structured_config",title:"Structured Configs example",sidebar_label:"Structured Configs example"},l=void 0,d={unversionedId:"advanced/instantiate_objects/structured_config",id:"version-1.2/advanced/instantiate_objects/structured_config",title:"Structured Configs example",description:"This example demonstrates the use of Structured Configs to instantiated objects.",source:"@site/versioned_docs/version-1.2/advanced/instantiate_objects/structured_config.md",sourceDirName:"advanced/instantiate_objects",slug:"/advanced/instantiate_objects/structured_config",permalink:"/docs/1.2/advanced/instantiate_objects/structured_config",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/advanced/instantiate_objects/structured_config.md",tags:[],version:"1.2",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"structured_config",title:"Structured Configs example",sidebar_label:"Structured Configs example"},sidebar:"docs",previous:{title:"Config files example",permalink:"/docs/1.2/advanced/instantiate_objects/config_files"},next:{title:"Compose API",permalink:"/docs/1.2/advanced/compose_api"}},p=[{value:"Example usage",id:"example-usage",children:[],level:4},{value:"Sample Output",id:"sample-output",children:[],level:4}],u={toc:p};function m(e){var t=e.components,n=(0,o.A)(e,s);return(0,a.mdx)("wrapper",(0,r.A)({},u,n,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)(i.C,{text:"Example applications",to:"examples/instantiate",mdxType:"ExampleGithubLink"}),(0,a.mdx)("p",null,"This example demonstrates the use of Structured Configs to instantiated objects."),(0,a.mdx)("h4",{id:"example-usage"},"Example usage"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app.py"',title:'"my_app.py"'},'class DBConnection:\n def __init__(self, driver: str, host: str, port: int) -> None:\n self.driver = driver\n self.host = host\n self.port = port\n\n def connect(self) -> None:\n print(f"{self.driver} connecting to {self.host}")\n\nclass MySQLConnection(DBConnection):\n def __init__(self, driver: str, host: str, port: int) -> None:\n super().__init__(driver=driver, host=host, port=port)\n\nclass PostgreSQLConnection(DBConnection):\n def __init__(self, driver: str, host: str, port: int, timeout: int) -> None:\n super().__init__(driver=driver, host=host, port=port)\n self.timeout = timeout\n\n@dataclass\nclass DBConfig:\n driver: str = MISSING\n host: str = "localhost"\n port: int = 80\n\n@dataclass\nclass MySQLConfig(DBConfig):\n _target_: str = "my_app.MySQLConnection"\n driver: str = "MySQL"\n port: int = 1234\n\n@dataclass\nclass PostGreSQLConfig(DBConfig):\n _target_: str = "my_app.PostgreSQLConnection"\n driver: str = "PostgreSQL"\n port: int = 5678\n timeout: int = 10\n\n@dataclass\nclass Config:\n defaults: List[Any] = field(default_factory=lambda: [{"db": "mysql"}])\n db: DBConfig = MISSING\n\n\ncs = ConfigStore.instance()\ncs.store(name="config", node=Config)\ncs.store(group="db", name="mysql", node=MySQLConfig)\ncs.store(group="db", name="postgresql", node=PostGreSQLConfig)\n\n@hydra.main(version_base=None, config_name="config")\ndef my_app(cfg: Config) -> None:\n connection = instantiate(cfg.db)\n connection.connect()\n\nif __name__ == "__main__":\n my_app()\n')),(0,a.mdx)("h4",{id:"sample-output"},"Sample Output"),(0,a.mdx)("div",{className:"row"},(0,a.mdx)("div",{className:"col col--6"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-bash"},"$ python my_app.py\nMySQL connecting to localhost:1234\n"))),(0,a.mdx)("div",{className:"col col--6"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-bash"},"$ python my_app.py db=postgresql\nPostgreSQL connecting to localhost:5678\n")))))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2cac4d70.d6188b75.js b/assets/js/2cac4d70.d6188b75.js deleted file mode 100644 index 560eea92e9..0000000000 --- a/assets/js/2cac4d70.d6188b75.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[4547],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>p,MDXProvider:()=>u,mdx:()=>f,useMDXComponents:()=>s,withMDXComponents:()=>m});var r=n(96540);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var p=r.createContext({}),m=function(e){return function(t){var n=s(t.components);return r.createElement(e,a({},t,{components:n}))}},s=function(e){var t=r.useContext(p),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},u=function(e){var t=s(e.components);return r.createElement(p.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},y=r.forwardRef((function(e,t){var n=e.components,i=e.mdxType,a=e.originalType,o=e.parentName,p=c(e,["components","mdxType","originalType","parentName"]),m=s(n),u=i,y=m["".concat(o,".").concat(u)]||m[u]||d[u]||a;return n?r.createElement(y,l(l({ref:t},p),{},{components:n})):r.createElement(y,l({ref:t},p))}));function f(e,t){var n=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var a=n.length,o=new Array(a);o[0]=y;var l={};for(var c in t)hasOwnProperty.call(t,c)&&(l[c]=t[c]);l.originalType=e,l.mdxType="string"==typeof e?e:i,o[1]=l;for(var p=2;p{n.d(t,{A:()=>c,C:()=>p});var r=n(58168),i=n(96540),a=n(75489),o=n(44586),l=n(74098);function c(e){return i.createElement(a.default,(0,r.A)({},e,{to:(t=e.to,c=(0,l.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==c?void 0:c.name)?n:"current"]+t),target:"_blank"}));var t,n,c}function p(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return i.createElement(c,e,i.createElement("span",null,"\xa0"),i.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},5267:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>p,default:()=>d,frontMatter:()=>c,metadata:()=>m,toc:()=>s});var r=n(58168),i=n(98587),a=(n(96540),n(15680)),o=n(49595),l=["components"],c={id:"minimal_example",title:"Minimal example"},p=void 0,m={unversionedId:"tutorials/structured_config/minimal_example",id:"version-1.1/tutorials/structured_config/minimal_example",title:"Minimal example",description:"There are four key elements in this example:",source:"@site/versioned_docs/version-1.1/tutorials/structured_config/1_minimal_example.md",sourceDirName:"tutorials/structured_config",slug:"/tutorials/structured_config/minimal_example",permalink:"/docs/1.1/tutorials/structured_config/minimal_example",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/tutorials/structured_config/1_minimal_example.md",tags:[],version:"1.1",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:1,frontMatter:{id:"minimal_example",title:"Minimal example"},sidebar:"version-1.1/docs",previous:{title:"Config Store API",permalink:"/docs/1.1/tutorials/structured_config/config_store"},next:{title:"A hierarchical static configuration",permalink:"/docs/1.1/tutorials/structured_config/hierarchical_static_config"}},s=[{value:"Duck-typing enables static type checking",id:"duck-typing-enables-static-type-checking",children:[],level:3},{value:"Structured Configs enable Hydra to catch type errors at runtime",id:"structured-configs-enable-hydra-to-catch-type-errors-at-runtime",children:[],level:3},{value:"Duck typing",id:"duck-typing",children:[],level:2}],u={toc:s};function d(e){var t=e.components,n=(0,i.A)(e,l);return(0,a.mdx)("wrapper",(0,r.A)({},u,n,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)(o.C,{to:"examples/tutorials/structured_configs/1_minimal",mdxType:"ExampleGithubLink"}),(0,a.mdx)("p",null,"There are four key elements in this example:"),(0,a.mdx)("ul",null,(0,a.mdx)("li",{parentName:"ul"},"A ",(0,a.mdx)("inlineCode",{parentName:"li"},"@dataclass")," describes the application's configuration"),(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"ConfigStore")," manages the Structured Config"),(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"cfg")," is ",(0,a.mdx)("inlineCode",{parentName:"li"},"duck typed")," as a ",(0,a.mdx)("inlineCode",{parentName:"li"},"MySQLConfig")," instead of a ",(0,a.mdx)("inlineCode",{parentName:"li"},"DictConfig")),(0,a.mdx)("li",{parentName:"ul"},"There is a subtle typo in the code below, can you spot it?")),(0,a.mdx)("p",null,"In this example, the config node stored in the ",(0,a.mdx)("inlineCode",{parentName:"p"},"ConfigStore")," replaces the traditional ",(0,a.mdx)("inlineCode",{parentName:"p"},"config.yaml")," file."),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app_type_error.py" {18}',title:'"my_app_type_error.py"',"{18}":!0},'from dataclasses import dataclass\n\nimport hydra\nfrom hydra.core.config_store import ConfigStore\n\n@dataclass\nclass MySQLConfig:\n host: str = "localhost"\n port: int = 3306\n\ncs = ConfigStore.instance()\n# Registering the Config class with the name \'config\'.\ncs.store(name="config", node=MySQLConfig)\n\n@hydra.main(config_path=None, config_name="config")\ndef my_app(cfg: MySQLConfig) -> None:\n # pork should be port!\n if cfg.pork == 80:\n print("Is this a webserver?!")\n\nif __name__ == "__main__":\n my_app()\n')),(0,a.mdx)("h3",{id:"duck-typing-enables-static-type-checking"},"Duck-typing enables static type checking"),(0,a.mdx)("p",null,"Duck-typing the config object as ",(0,a.mdx)("inlineCode",{parentName:"p"},"MySQLConfig")," enables static type checkers like ",(0,a.mdx)("inlineCode",{parentName:"p"},"mypy")," to catch\ntype errors before you run your code:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="$ mypy my_app_type_error.py"',title:'"$',mypy:!0,'my_app_type_error.py"':!0},'my_app_type_error.py:22: error: "MySQLConfig" has no attribute "pork"\nFound 1 error in 1 file (checked 1 source file)\n')),(0,a.mdx)("h3",{id:"structured-configs-enable-hydra-to-catch-type-errors-at-runtime"},"Structured Configs enable Hydra to catch type errors at runtime"),(0,a.mdx)("p",null,"If you forget to run ",(0,a.mdx)("inlineCode",{parentName:"p"},"mypy"),", Hydra will report the error at runtime:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="$ python my_app_type_error.py"',title:'"$',python:!0,'my_app_type_error.py"':!0},"Traceback (most recent call last):\n File \"my_app_type_error.py\", line 22, in my_app\n if cfg.pork == 80:\nomegaconf.errors.ConfigAttributeError: Key 'pork' not in 'MySQLConfig'\n full_key: pork\n object_type=MySQLConfig\n\nSet the environment variable HYDRA_FULL_ERROR=1 for a complete stack trace.\n")),(0,a.mdx)("p",null,"Hydra will also catch typos, or type errors in the command line:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre"},"$ python my_app_type_error.py port=fail\nError merging override port=fail\nValue 'fail' could not be converted to Integer\n full_key: port\n object_type=MySQLConfig\n")),(0,a.mdx)("p",null,"We will see additional types of runtime errors that Hydra can catch later in this tutorial. Such as:"),(0,a.mdx)("ul",null,(0,a.mdx)("li",{parentName:"ul"},"Trying to read or write a non existent field in your config object"),(0,a.mdx)("li",{parentName:"ul"},"Assigning a value that is incompatible with the declared type"),(0,a.mdx)("li",{parentName:"ul"},"Attempting to modify a ",(0,a.mdx)("a",{parentName:"li",href:"https://omegaconf.readthedocs.io/en/latest/structured_config.html#frozen"},"frozen config"))),(0,a.mdx)("h2",{id:"duck-typing"},"Duck typing"),(0,a.mdx)("p",null,"In the example above ",(0,a.mdx)("inlineCode",{parentName:"p"},"cfg")," is duck typed as ",(0,a.mdx)("inlineCode",{parentName:"p"},"MySQLConfig"),".\nIt is actually an instance of ",(0,a.mdx)("inlineCode",{parentName:"p"},"DictConfig"),". The duck typing enables static type checking by tools like Mypy or PyCharm.\nThis reduces development time by catching coding errors before you run your application."),(0,a.mdx)("p",null,"The name ",(0,a.mdx)("a",{parentName:"p",href:"https://en.wikipedia.org/wiki/Duck_typing"},"Duck typing"),' comes from the phrase "If it walks like a duck, swims like a duck, and quacks like a duck, then it probably is a duck".\nIt can be useful when you care about the methods or attributes of an object, not the actual type of the object.'))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2cac4d70.eeda3555.js b/assets/js/2cac4d70.eeda3555.js new file mode 100644 index 0000000000..9be38354dd --- /dev/null +++ b/assets/js/2cac4d70.eeda3555.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[4547],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>p,MDXProvider:()=>u,mdx:()=>f,useMDXComponents:()=>s,withMDXComponents:()=>m});var r=n(96540);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var p=r.createContext({}),m=function(e){return function(t){var n=s(t.components);return r.createElement(e,a({},t,{components:n}))}},s=function(e){var t=r.useContext(p),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},u=function(e){var t=s(e.components);return r.createElement(p.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},y=r.forwardRef((function(e,t){var n=e.components,i=e.mdxType,a=e.originalType,o=e.parentName,p=c(e,["components","mdxType","originalType","parentName"]),m=s(n),u=i,y=m["".concat(o,".").concat(u)]||m[u]||d[u]||a;return n?r.createElement(y,l(l({ref:t},p),{},{components:n})):r.createElement(y,l({ref:t},p))}));function f(e,t){var n=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var a=n.length,o=new Array(a);o[0]=y;var l={};for(var c in t)hasOwnProperty.call(t,c)&&(l[c]=t[c]);l.originalType=e,l.mdxType="string"==typeof e?e:i,o[1]=l;for(var p=2;p{n.d(t,{A:()=>c,C:()=>p});var r=n(58168),i=n(96540),a=n(75489),o=n(44586),l=n(74098);function c(e){return i.createElement(a.default,(0,r.A)({},e,{to:(t=e.to,c=(0,l.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==c?void 0:c.name)?n:"current"]+t),target:"_blank"}));var t,n,c}function p(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return i.createElement(c,e,i.createElement("span",null,"\xa0"),i.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},5267:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>p,default:()=>d,frontMatter:()=>c,metadata:()=>m,toc:()=>s});var r=n(58168),i=n(98587),a=(n(96540),n(15680)),o=n(49595),l=["components"],c={id:"minimal_example",title:"Minimal example"},p=void 0,m={unversionedId:"tutorials/structured_config/minimal_example",id:"version-1.1/tutorials/structured_config/minimal_example",title:"Minimal example",description:"There are four key elements in this example:",source:"@site/versioned_docs/version-1.1/tutorials/structured_config/1_minimal_example.md",sourceDirName:"tutorials/structured_config",slug:"/tutorials/structured_config/minimal_example",permalink:"/docs/1.1/tutorials/structured_config/minimal_example",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/tutorials/structured_config/1_minimal_example.md",tags:[],version:"1.1",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:1,frontMatter:{id:"minimal_example",title:"Minimal example"},sidebar:"version-1.1/docs",previous:{title:"Config Store API",permalink:"/docs/1.1/tutorials/structured_config/config_store"},next:{title:"A hierarchical static configuration",permalink:"/docs/1.1/tutorials/structured_config/hierarchical_static_config"}},s=[{value:"Duck-typing enables static type checking",id:"duck-typing-enables-static-type-checking",children:[],level:3},{value:"Structured Configs enable Hydra to catch type errors at runtime",id:"structured-configs-enable-hydra-to-catch-type-errors-at-runtime",children:[],level:3},{value:"Duck typing",id:"duck-typing",children:[],level:2}],u={toc:s};function d(e){var t=e.components,n=(0,i.A)(e,l);return(0,a.mdx)("wrapper",(0,r.A)({},u,n,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)(o.C,{to:"examples/tutorials/structured_configs/1_minimal",mdxType:"ExampleGithubLink"}),(0,a.mdx)("p",null,"There are four key elements in this example:"),(0,a.mdx)("ul",null,(0,a.mdx)("li",{parentName:"ul"},"A ",(0,a.mdx)("inlineCode",{parentName:"li"},"@dataclass")," describes the application's configuration"),(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"ConfigStore")," manages the Structured Config"),(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"cfg")," is ",(0,a.mdx)("inlineCode",{parentName:"li"},"duck typed")," as a ",(0,a.mdx)("inlineCode",{parentName:"li"},"MySQLConfig")," instead of a ",(0,a.mdx)("inlineCode",{parentName:"li"},"DictConfig")),(0,a.mdx)("li",{parentName:"ul"},"There is a subtle typo in the code below, can you spot it?")),(0,a.mdx)("p",null,"In this example, the config node stored in the ",(0,a.mdx)("inlineCode",{parentName:"p"},"ConfigStore")," replaces the traditional ",(0,a.mdx)("inlineCode",{parentName:"p"},"config.yaml")," file."),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app_type_error.py" {18}',title:'"my_app_type_error.py"',"{18}":!0},'from dataclasses import dataclass\n\nimport hydra\nfrom hydra.core.config_store import ConfigStore\n\n@dataclass\nclass MySQLConfig:\n host: str = "localhost"\n port: int = 3306\n\ncs = ConfigStore.instance()\n# Registering the Config class with the name \'config\'.\ncs.store(name="config", node=MySQLConfig)\n\n@hydra.main(config_path=None, config_name="config")\ndef my_app(cfg: MySQLConfig) -> None:\n # pork should be port!\n if cfg.pork == 80:\n print("Is this a webserver?!")\n\nif __name__ == "__main__":\n my_app()\n')),(0,a.mdx)("h3",{id:"duck-typing-enables-static-type-checking"},"Duck-typing enables static type checking"),(0,a.mdx)("p",null,"Duck-typing the config object as ",(0,a.mdx)("inlineCode",{parentName:"p"},"MySQLConfig")," enables static type checkers like ",(0,a.mdx)("inlineCode",{parentName:"p"},"mypy")," to catch\ntype errors before you run your code:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="$ mypy my_app_type_error.py"',title:'"$',mypy:!0,'my_app_type_error.py"':!0},'my_app_type_error.py:22: error: "MySQLConfig" has no attribute "pork"\nFound 1 error in 1 file (checked 1 source file)\n')),(0,a.mdx)("h3",{id:"structured-configs-enable-hydra-to-catch-type-errors-at-runtime"},"Structured Configs enable Hydra to catch type errors at runtime"),(0,a.mdx)("p",null,"If you forget to run ",(0,a.mdx)("inlineCode",{parentName:"p"},"mypy"),", Hydra will report the error at runtime:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="$ python my_app_type_error.py"',title:'"$',python:!0,'my_app_type_error.py"':!0},"Traceback (most recent call last):\n File \"my_app_type_error.py\", line 22, in my_app\n if cfg.pork == 80:\nomegaconf.errors.ConfigAttributeError: Key 'pork' not in 'MySQLConfig'\n full_key: pork\n object_type=MySQLConfig\n\nSet the environment variable HYDRA_FULL_ERROR=1 for a complete stack trace.\n")),(0,a.mdx)("p",null,"Hydra will also catch typos, or type errors in the command line:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre"},"$ python my_app_type_error.py port=fail\nError merging override port=fail\nValue 'fail' could not be converted to Integer\n full_key: port\n object_type=MySQLConfig\n")),(0,a.mdx)("p",null,"We will see additional types of runtime errors that Hydra can catch later in this tutorial. Such as:"),(0,a.mdx)("ul",null,(0,a.mdx)("li",{parentName:"ul"},"Trying to read or write a non existent field in your config object"),(0,a.mdx)("li",{parentName:"ul"},"Assigning a value that is incompatible with the declared type"),(0,a.mdx)("li",{parentName:"ul"},"Attempting to modify a ",(0,a.mdx)("a",{parentName:"li",href:"https://omegaconf.readthedocs.io/en/latest/structured_config.html#frozen"},"frozen config"))),(0,a.mdx)("h2",{id:"duck-typing"},"Duck typing"),(0,a.mdx)("p",null,"In the example above ",(0,a.mdx)("inlineCode",{parentName:"p"},"cfg")," is duck typed as ",(0,a.mdx)("inlineCode",{parentName:"p"},"MySQLConfig"),".\nIt is actually an instance of ",(0,a.mdx)("inlineCode",{parentName:"p"},"DictConfig"),". The duck typing enables static type checking by tools like Mypy or PyCharm.\nThis reduces development time by catching coding errors before you run your application."),(0,a.mdx)("p",null,"The name ",(0,a.mdx)("a",{parentName:"p",href:"https://en.wikipedia.org/wiki/Duck_typing"},"Duck typing"),' comes from the phrase "If it walks like a duck, swims like a duck, and quacks like a duck, then it probably is a duck".\nIt can be useful when you care about the methods or attributes of an object, not the actual type of the object.'))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2ceb009d.ca639960.js b/assets/js/2ceb009d.ca639960.js deleted file mode 100644 index 76372373ff..0000000000 --- a/assets/js/2ceb009d.ca639960.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[8232],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>l,MDXProvider:()=>d,mdx:()=>g,useMDXComponents:()=>u,withMDXComponents:()=>p});var r=t(96540);function o(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(o[t]=e[t]);return o}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(o[t]=e[t])}return o}var l=r.createContext({}),p=function(e){return function(n){var t=u(n.components);return r.createElement(e,i({},n,{components:t}))}},u=function(e){var n=r.useContext(l),t=n;return e&&(t="function"==typeof e?e(n):s(s({},n),e)),t},d=function(e){var n=u(e.components);return r.createElement(l.Provider,{value:n},e.children)},f={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},m=r.forwardRef((function(e,n){var t=e.components,o=e.mdxType,i=e.originalType,a=e.parentName,l=c(e,["components","mdxType","originalType","parentName"]),p=u(t),d=o,m=p["".concat(a,".").concat(d)]||p[d]||f[d]||i;return t?r.createElement(m,s(s({ref:n},l),{},{components:t})):r.createElement(m,s({ref:n},l))}));function g(e,n){var t=arguments,o=n&&n.mdxType;if("string"==typeof e||o){var i=t.length,a=new Array(i);a[0]=m;var s={};for(var c in n)hasOwnProperty.call(n,c)&&(s[c]=n[c]);s.originalType=e,s.mdxType="string"==typeof e?e:o,a[1]=s;for(var l=2;l{t.r(n),t.d(n,{contentTitle:()=>c,default:()=>d,frontMatter:()=>s,metadata:()=>l,toc:()=>p});var r=t(58168),o=t(98587),i=(t(96540),t(15680)),a=["components"],s={id:"config_store",title:"Config Store API"},c=void 0,l={unversionedId:"tutorials/structured_config/config_store",id:"version-1.0/tutorials/structured_config/config_store",title:"Config Store API",description:"ConfigStore is a singleton storing configs in memory.",source:"@site/versioned_docs/version-1.0/tutorials/structured_config/10_config_store.md",sourceDirName:"tutorials/structured_config",slug:"/tutorials/structured_config/config_store",permalink:"/docs/1.0/tutorials/structured_config/config_store",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.0/tutorials/structured_config/10_config_store.md",tags:[],version:"1.0",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:10,frontMatter:{id:"config_store",title:"Config Store API"},sidebar:"version-1.0/docs",previous:{title:"Dynamic schema with many configs",permalink:"/docs/1.0/tutorials/structured_config/dynamic_schema"},next:{title:"Overview",permalink:"/docs/1.0/patterns/instantiate_objects/overview"}},p=[{value:"API",id:"api",children:[],level:3},{value:"Example node values",id:"example-node-values",children:[],level:3}],u={toc:p};function d(e){var n=e.components,t=(0,o.A)(e,a);return(0,i.mdx)("wrapper",(0,r.A)({},u,t,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,(0,i.mdx)("inlineCode",{parentName:"p"},"ConfigStore")," is a singleton storing configs in memory.\nThe primary API for interacting with the ",(0,i.mdx)("inlineCode",{parentName:"p"},"ConfigStore")," is the store method described below."),(0,i.mdx)("h3",{id:"api"},"API"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python"},'class ConfigStore(metaclass=Singleton):\n def store(\n self,\n name: str,\n node: Any,\n group: Optional[str] = None,\n package: Optional[str] = "_group_",\n provider: Optional[str] = None,\n ) -> None:\n """\n Stores a config node into the repository\n :param name: config name\n :param node: config node, can be DictConfig, ListConfig,\n Structured configs and even dict and list\n :param group: config group, subgroup separator is \'/\',\n for example hydra/launcher\n :param package: Config node parent hierarchy.\n Child separator is \'.\', for example foo.bar.baz\n :param provider: the name of the module/app providing this config.\n Helps debugging.\n """\n ...\n')),(0,i.mdx)("h3",{id:"example-node-values"},"Example node values"),(0,i.mdx)("p",null,"A few examples of supported node values parameters:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python"},'@dataclass\nclass MySQLConfig:\n host: str = "localhost"\n port: int = 3306\n\n# Using the type\ncs.store(name="config1", node=MySQLConfig)\n# Using an instance, overriding some default values\ncs.store(name="config2", node=MySQLConfig(host="test.db", port=3307))\n# Using a dictionary, forfeiting runtime type safety\ncs.store(name="config3", node={"host": "localhost", "port": 3308})\n')))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2ceb009d.e006753f.js b/assets/js/2ceb009d.e006753f.js new file mode 100644 index 0000000000..2fc22426dc --- /dev/null +++ b/assets/js/2ceb009d.e006753f.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[8232],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>l,MDXProvider:()=>u,mdx:()=>g,useMDXComponents:()=>d,withMDXComponents:()=>p});var r=t(96540);function o(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(o[t]=e[t]);return o}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(o[t]=e[t])}return o}var l=r.createContext({}),p=function(e){return function(n){var t=d(n.components);return r.createElement(e,i({},n,{components:t}))}},d=function(e){var n=r.useContext(l),t=n;return e&&(t="function"==typeof e?e(n):s(s({},n),e)),t},u=function(e){var n=d(e.components);return r.createElement(l.Provider,{value:n},e.children)},f={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},m=r.forwardRef((function(e,n){var t=e.components,o=e.mdxType,i=e.originalType,a=e.parentName,l=c(e,["components","mdxType","originalType","parentName"]),p=d(t),u=o,m=p["".concat(a,".").concat(u)]||p[u]||f[u]||i;return t?r.createElement(m,s(s({ref:n},l),{},{components:t})):r.createElement(m,s({ref:n},l))}));function g(e,n){var t=arguments,o=n&&n.mdxType;if("string"==typeof e||o){var i=t.length,a=new Array(i);a[0]=m;var s={};for(var c in n)hasOwnProperty.call(n,c)&&(s[c]=n[c]);s.originalType=e,s.mdxType="string"==typeof e?e:o,a[1]=s;for(var l=2;l{t.r(n),t.d(n,{contentTitle:()=>c,default:()=>u,frontMatter:()=>s,metadata:()=>l,toc:()=>p});var r=t(58168),o=t(98587),i=(t(96540),t(15680)),a=["components"],s={id:"config_store",title:"Config Store API"},c=void 0,l={unversionedId:"tutorials/structured_config/config_store",id:"version-1.0/tutorials/structured_config/config_store",title:"Config Store API",description:"ConfigStore is a singleton storing configs in memory.",source:"@site/versioned_docs/version-1.0/tutorials/structured_config/10_config_store.md",sourceDirName:"tutorials/structured_config",slug:"/tutorials/structured_config/config_store",permalink:"/docs/1.0/tutorials/structured_config/config_store",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.0/tutorials/structured_config/10_config_store.md",tags:[],version:"1.0",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:10,frontMatter:{id:"config_store",title:"Config Store API"},sidebar:"version-1.0/docs",previous:{title:"Dynamic schema with many configs",permalink:"/docs/1.0/tutorials/structured_config/dynamic_schema"},next:{title:"Overview",permalink:"/docs/1.0/patterns/instantiate_objects/overview"}},p=[{value:"API",id:"api",children:[],level:3},{value:"Example node values",id:"example-node-values",children:[],level:3}],d={toc:p};function u(e){var n=e.components,t=(0,o.A)(e,a);return(0,i.mdx)("wrapper",(0,r.A)({},d,t,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,(0,i.mdx)("inlineCode",{parentName:"p"},"ConfigStore")," is a singleton storing configs in memory.\nThe primary API for interacting with the ",(0,i.mdx)("inlineCode",{parentName:"p"},"ConfigStore")," is the store method described below."),(0,i.mdx)("h3",{id:"api"},"API"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python"},'class ConfigStore(metaclass=Singleton):\n def store(\n self,\n name: str,\n node: Any,\n group: Optional[str] = None,\n package: Optional[str] = "_group_",\n provider: Optional[str] = None,\n ) -> None:\n """\n Stores a config node into the repository\n :param name: config name\n :param node: config node, can be DictConfig, ListConfig,\n Structured configs and even dict and list\n :param group: config group, subgroup separator is \'/\',\n for example hydra/launcher\n :param package: Config node parent hierarchy.\n Child separator is \'.\', for example foo.bar.baz\n :param provider: the name of the module/app providing this config.\n Helps debugging.\n """\n ...\n')),(0,i.mdx)("h3",{id:"example-node-values"},"Example node values"),(0,i.mdx)("p",null,"A few examples of supported node values parameters:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python"},'@dataclass\nclass MySQLConfig:\n host: str = "localhost"\n port: int = 3306\n\n# Using the type\ncs.store(name="config1", node=MySQLConfig)\n# Using an instance, overriding some default values\ncs.store(name="config2", node=MySQLConfig(host="test.db", port=3307))\n# Using a dictionary, forfeiting runtime type safety\ncs.store(name="config3", node={"host": "localhost", "port": 3308})\n')))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2d3c34e0.86d12028.js b/assets/js/2d3c34e0.86d12028.js new file mode 100644 index 0000000000..cf375b7c8e --- /dev/null +++ b/assets/js/2d3c34e0.86d12028.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[5673],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>d,MDXProvider:()=>u,mdx:()=>f,useMDXComponents:()=>p,withMDXComponents:()=>s});var a=n(96540);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function l(){return l=Object.assign||function(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var l=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var d=a.createContext({}),s=function(e){return function(t){var n=p(t.components);return a.createElement(e,l({},t,{components:n}))}},p=function(e){var t=a.useContext(d),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},u=function(e){var t=p(e.components);return a.createElement(d.Provider,{value:t},e.children)},c={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},h=a.forwardRef((function(e,t){var n=e.components,r=e.mdxType,l=e.originalType,o=e.parentName,d=m(e,["components","mdxType","originalType","parentName"]),s=p(n),u=r,h=s["".concat(o,".").concat(u)]||s[u]||c[u]||l;return n?a.createElement(h,i(i({ref:t},d),{},{components:n})):a.createElement(h,i({ref:t},d))}));function f(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var l=n.length,o=new Array(l);o[0]=h;var i={};for(var m in t)hasOwnProperty.call(t,m)&&(i[m]=t[m]);i.originalType=e,i.mdxType="string"==typeof e?e:r,o[1]=i;for(var d=2;d{n.r(t),n.d(t,{contentTitle:()=>m,default:()=>u,frontMatter:()=>i,metadata:()=>d,toc:()=>s});var a=n(58168),r=n(98587),l=(n(96540),n(15680)),o=(n(86025),n(75489),["components"]),i={id:"intro",title:"Getting started",sidebar_label:"Getting started"},m=void 0,d={unversionedId:"intro",id:"version-0.11/intro",title:"Getting started",description:"Introduction",source:"@site/versioned_docs/version-0.11/intro.md",sourceDirName:".",slug:"/intro",permalink:"/docs/0.11/intro",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-0.11/intro.md",tags:[],version:"0.11",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"intro",title:"Getting started",sidebar_label:"Getting started"},sidebar:"version-0.11/docs",next:{title:"Simple command line application",permalink:"/docs/0.11/tutorial/simple_cli"}},s=[{value:"Introduction",id:"introduction",children:[{value:"Key features:",id:"key-features",children:[],level:3}],level:2},{value:"Versions",id:"versions",children:[],level:2},{value:"Quick start guide",id:"quick-start-guide",children:[{value:"Installation",id:"installation",children:[],level:3},{value:"Basic example",id:"basic-example",children:[],level:3},{value:"Composition example",id:"composition-example",children:[],level:3},{value:"Multirun",id:"multirun",children:[],level:3}],level:2},{value:"Other stuff",id:"other-stuff",children:[{value:"Community",id:"community",children:[],level:3},{value:"Citing Hydra",id:"citing-hydra",children:[],level:3}],level:2}],p={toc:s};function u(e){var t=e.components,n=(0,r.A)(e,o);return(0,l.mdx)("wrapper",(0,a.A)({},p,n,{components:t,mdxType:"MDXLayout"}),(0,l.mdx)("h2",{id:"introduction"},"Introduction"),(0,l.mdx)("p",null,"Hydra is an open-source Python framework that simplifies the development of research and other complex applications.\nThe key feature is the ability to dynamically create a hierarchical configuration by composition and override it through config files and the command line.\nThe name Hydra comes from its ability to run multiple similar jobs - much like a Hydra with multiple heads."),(0,l.mdx)("h3",{id:"key-features"},"Key features:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},"Hierarchical configuration composable from multiple sources"),(0,l.mdx)("li",{parentName:"ul"},"Configuration can be specified or overridden from the command line"),(0,l.mdx)("li",{parentName:"ul"},"Dynamic command line tab completion"),(0,l.mdx)("li",{parentName:"ul"},"Run your application locally or launch it to run remotely"),(0,l.mdx)("li",{parentName:"ul"},"Run multiple jobs with different arguments with a single command")),(0,l.mdx)("h2",{id:"versions"},"Versions"),(0,l.mdx)("p",null,"Hydra supports Linux, Mac and Windows.",(0,l.mdx)("br",{parentName:"p"}),"\n","Use the version switcher in the top bar to switch between documentation versions."),(0,l.mdx)("table",null,(0,l.mdx)("thead",{parentName:"table"},(0,l.mdx)("tr",{parentName:"thead"},(0,l.mdx)("th",{parentName:"tr",align:null}),(0,l.mdx)("th",{parentName:"tr",align:null},"Version"),(0,l.mdx)("th",{parentName:"tr",align:null},"Release notes"),(0,l.mdx)("th",{parentName:"tr",align:null},"Python Versions"))),(0,l.mdx)("tbody",{parentName:"table"},(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null}),(0,l.mdx)("td",{parentName:"tr",align:null},"1.3 (Stable)"),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v1.3.0"},"Release notes")),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("strong",{parentName:"td"},"3.6 - 3.11"))),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null}),(0,l.mdx)("td",{parentName:"tr",align:null},"1.2"),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v1.2.0"},"Release notes")),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("strong",{parentName:"td"},"3.6 - 3.10"))),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null}),(0,l.mdx)("td",{parentName:"tr",align:null},"1.1"),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v1.1.1"},"Release notes")),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("strong",{parentName:"td"},"3.6 - 3.9"))),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null}),(0,l.mdx)("td",{parentName:"tr",align:null},"1.0"),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v1.0.7"},"Release notes")),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("strong",{parentName:"td"},"3.6 - 3.8"))),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u25ba"),(0,l.mdx)("td",{parentName:"tr",align:null},"0.11"),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v0.11.3"},"Release notes")),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("strong",{parentName:"td"},"2.7, 3.5 - 3.8"))))),(0,l.mdx)("h2",{id:"quick-start-guide"},"Quick start guide"),(0,l.mdx)("p",null,"This guide will show you some of the most important features of Hydra.\nRead the ",(0,l.mdx)("a",{parentName:"p",href:"/docs/0.11/tutorial/simple_cli"},"tutorial")," to gain a deeper understanding."),(0,l.mdx)("h3",{id:"installation"},"Installation"),(0,l.mdx)("p",null,"Install Hydra 0.11 with ",(0,l.mdx)("inlineCode",{parentName:"p"},"pip install hydra-core --upgrade"),"."),(0,l.mdx)("h3",{id:"basic-example"},"Basic example"),(0,l.mdx)("p",null,"Configuration file: ",(0,l.mdx)("inlineCode",{parentName:"p"},"config.yaml")),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml"},"db:\n driver: mysql\n user: omry\n pass: secret\n")),(0,l.mdx)("p",null,"Python file: ",(0,l.mdx)("inlineCode",{parentName:"p"},"my_app.py")),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:"{4-6}","{4-6}":!0},'import hydra\nfrom omegaconf import DictConfig\n\n@hydra.main(config_path="config.yaml")\ndef my_app(cfg : DictConfig) -> None:\n print(OmegaConf.to_yaml(cfg))\n\nif __name__ == "__main__":\n my_app()\n')),(0,l.mdx)("p",null,"You can learn more about OmegaConf ",(0,l.mdx)("a",{parentName:"p",href:"https://omegaconf.readthedocs.io/en/latest/usage.html#access-and-manipulation"},"here")," later."),(0,l.mdx)("p",null,(0,l.mdx)("inlineCode",{parentName:"p"},"config.yaml")," is loaded automatically when you run your application"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py\ndb:\n driver: mysql\n pass: secret\n user: omry\n")),(0,l.mdx)("p",null,"You can override values in the loaded config from the command line:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{4-5}","{4-5}":!0},"$ python my_app.py db.user=root db.pass=1234\ndb:\n driver: mysql\n user: root\n pass: 1234\n")),(0,l.mdx)("h3",{id:"composition-example"},"Composition example"),(0,l.mdx)("p",null,"You may want to alternate between two different databases. To support this create a ",(0,l.mdx)("inlineCode",{parentName:"p"},"config group")," named db,\nand place one config file for each alternative inside:\nThe directory structure of our application now looks like:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-text"},"\u251c\u2500\u2500 db\n\u2502 \u251c\u2500\u2500 mysql.yaml\n\u2502 \u2514\u2500\u2500 postgresql.yaml\n\u251c\u2500\u2500 config.yaml\n\u2514\u2500\u2500 my_app.py\n")),(0,l.mdx)("p",null,"Here is the new ",(0,l.mdx)("inlineCode",{parentName:"p"},"config.yaml")),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - db: mysql\n# some other config options in your config file.\nwebsite:\n domain: example.com\n")),(0,l.mdx)("p",null,(0,l.mdx)("inlineCode",{parentName:"p"},"defaults")," is a special directive telling Hydra to use db/mysql.yaml when composing the configuration object.\nThe resulting cfg object is a composition of configs from defaults with configs specified in your ",(0,l.mdx)("inlineCode",{parentName:"p"},"config.yaml"),"."),(0,l.mdx)("p",null,"You can now choose which database configuration to use from the and override values from the command line: "),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py db=postgresql db.timeout=20\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 20\n user: postgres_user\nwebsite:\n domain: example.com\n")),(0,l.mdx)("p",null,"You can have as many config groups as you need."),(0,l.mdx)("h3",{id:"multirun"},"Multirun"),(0,l.mdx)("p",null,"You can run your function multiple times with different configuration easily with the ",(0,l.mdx)("inlineCode",{parentName:"p"},"--multirun|-m")," flag."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre"},"$ python my_app.py --multirun db=mysql,postgresql\n[HYDRA] Sweep output dir : multirun/2020-01-09/01-16-29\n[HYDRA] Launching 2 jobs locally\n[HYDRA] #0 : db=mysql\ndb:\n driver: mysql\n pass: secret\n user: omry\nwebsite:\n domain: example.com\n\n[HYDRA] #1 : db=postgresql\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 10\n user: postgres_user\nwebsite:\n domain: example.com\n")),(0,l.mdx)("p",null,"There is a whole lot more to Hydra. Read the ",(0,l.mdx)("a",{parentName:"p",href:"/docs/0.11/tutorial/simple_cli"},"tutorial")," to learn more."),(0,l.mdx)("h2",{id:"other-stuff"},"Other stuff"),(0,l.mdx)("h3",{id:"community"},"Community"),(0,l.mdx)("p",null,"Ask questions on github or StackOverflow (Use the tag #fb-hydra):"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("a",{parentName:"li",href:"https://github.com/facebookresearch/hydra/discussions"},"github")),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("a",{parentName:"li",href:"https://stackoverflow.com/questions/tagged/fb-hydra"},"StackOverflow"))),(0,l.mdx)("p",null,"Follow Hydra on Twitter and Facebook:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("a",{parentName:"li",href:"https://www.facebook.com/Hydra-Framework-109364473802509/"},"Facebook page")),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("a",{parentName:"li",href:"https://twitter.com/Hydra_Framework"},"Twitter"))),(0,l.mdx)("h3",{id:"citing-hydra"},"Citing Hydra"),(0,l.mdx)("p",null,"If you use Hydra in your research please use the following BibTeX entry:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-text"},"@Misc{Yadan2019Hydra,\n author = {Omry Yadan},\n title = {Hydra - A framework for elegantly configuring complex applications},\n howpublished = {Github},\n year = {2019},\n url = {https://github.com/facebookresearch/hydra}\n}\n")))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2d3c34e0.f2a03fd7.js b/assets/js/2d3c34e0.f2a03fd7.js deleted file mode 100644 index 9a22f17160..0000000000 --- a/assets/js/2d3c34e0.f2a03fd7.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[5673],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>d,MDXProvider:()=>u,mdx:()=>f,useMDXComponents:()=>p,withMDXComponents:()=>s});var a=n(96540);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function l(){return l=Object.assign||function(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var l=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var d=a.createContext({}),s=function(e){return function(t){var n=p(t.components);return a.createElement(e,l({},t,{components:n}))}},p=function(e){var t=a.useContext(d),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},u=function(e){var t=p(e.components);return a.createElement(d.Provider,{value:t},e.children)},c={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},h=a.forwardRef((function(e,t){var n=e.components,r=e.mdxType,l=e.originalType,o=e.parentName,d=m(e,["components","mdxType","originalType","parentName"]),s=p(n),u=r,h=s["".concat(o,".").concat(u)]||s[u]||c[u]||l;return n?a.createElement(h,i(i({ref:t},d),{},{components:n})):a.createElement(h,i({ref:t},d))}));function f(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var l=n.length,o=new Array(l);o[0]=h;var i={};for(var m in t)hasOwnProperty.call(t,m)&&(i[m]=t[m]);i.originalType=e,i.mdxType="string"==typeof e?e:r,o[1]=i;for(var d=2;d{n.r(t),n.d(t,{contentTitle:()=>m,default:()=>u,frontMatter:()=>i,metadata:()=>d,toc:()=>s});var a=n(58168),r=n(98587),l=(n(96540),n(15680)),o=(n(86025),n(75489),["components"]),i={id:"intro",title:"Getting started",sidebar_label:"Getting started"},m=void 0,d={unversionedId:"intro",id:"version-0.11/intro",title:"Getting started",description:"Introduction",source:"@site/versioned_docs/version-0.11/intro.md",sourceDirName:".",slug:"/intro",permalink:"/docs/0.11/intro",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-0.11/intro.md",tags:[],version:"0.11",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"intro",title:"Getting started",sidebar_label:"Getting started"},sidebar:"version-0.11/docs",next:{title:"Simple command line application",permalink:"/docs/0.11/tutorial/simple_cli"}},s=[{value:"Introduction",id:"introduction",children:[{value:"Key features:",id:"key-features",children:[],level:3}],level:2},{value:"Versions",id:"versions",children:[],level:2},{value:"Quick start guide",id:"quick-start-guide",children:[{value:"Installation",id:"installation",children:[],level:3},{value:"Basic example",id:"basic-example",children:[],level:3},{value:"Composition example",id:"composition-example",children:[],level:3},{value:"Multirun",id:"multirun",children:[],level:3}],level:2},{value:"Other stuff",id:"other-stuff",children:[{value:"Community",id:"community",children:[],level:3},{value:"Citing Hydra",id:"citing-hydra",children:[],level:3}],level:2}],p={toc:s};function u(e){var t=e.components,n=(0,r.A)(e,o);return(0,l.mdx)("wrapper",(0,a.A)({},p,n,{components:t,mdxType:"MDXLayout"}),(0,l.mdx)("h2",{id:"introduction"},"Introduction"),(0,l.mdx)("p",null,"Hydra is an open-source Python framework that simplifies the development of research and other complex applications.\nThe key feature is the ability to dynamically create a hierarchical configuration by composition and override it through config files and the command line.\nThe name Hydra comes from its ability to run multiple similar jobs - much like a Hydra with multiple heads."),(0,l.mdx)("h3",{id:"key-features"},"Key features:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},"Hierarchical configuration composable from multiple sources"),(0,l.mdx)("li",{parentName:"ul"},"Configuration can be specified or overridden from the command line"),(0,l.mdx)("li",{parentName:"ul"},"Dynamic command line tab completion"),(0,l.mdx)("li",{parentName:"ul"},"Run your application locally or launch it to run remotely"),(0,l.mdx)("li",{parentName:"ul"},"Run multiple jobs with different arguments with a single command")),(0,l.mdx)("h2",{id:"versions"},"Versions"),(0,l.mdx)("p",null,"Hydra supports Linux, Mac and Windows.",(0,l.mdx)("br",{parentName:"p"}),"\n","Use the version switcher in the top bar to switch between documentation versions."),(0,l.mdx)("table",null,(0,l.mdx)("thead",{parentName:"table"},(0,l.mdx)("tr",{parentName:"thead"},(0,l.mdx)("th",{parentName:"tr",align:null}),(0,l.mdx)("th",{parentName:"tr",align:null},"Version"),(0,l.mdx)("th",{parentName:"tr",align:null},"Release notes"),(0,l.mdx)("th",{parentName:"tr",align:null},"Python Versions"))),(0,l.mdx)("tbody",{parentName:"table"},(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null}),(0,l.mdx)("td",{parentName:"tr",align:null},"1.3 (Stable)"),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v1.3.0"},"Release notes")),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("strong",{parentName:"td"},"3.6 - 3.11"))),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null}),(0,l.mdx)("td",{parentName:"tr",align:null},"1.2"),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v1.2.0"},"Release notes")),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("strong",{parentName:"td"},"3.6 - 3.10"))),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null}),(0,l.mdx)("td",{parentName:"tr",align:null},"1.1"),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v1.1.1"},"Release notes")),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("strong",{parentName:"td"},"3.6 - 3.9"))),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null}),(0,l.mdx)("td",{parentName:"tr",align:null},"1.0"),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v1.0.7"},"Release notes")),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("strong",{parentName:"td"},"3.6 - 3.8"))),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u25ba"),(0,l.mdx)("td",{parentName:"tr",align:null},"0.11"),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("a",{parentName:"td",href:"https://github.com/facebookresearch/hydra/releases/tag/v0.11.3"},"Release notes")),(0,l.mdx)("td",{parentName:"tr",align:null},(0,l.mdx)("strong",{parentName:"td"},"2.7, 3.5 - 3.8"))))),(0,l.mdx)("h2",{id:"quick-start-guide"},"Quick start guide"),(0,l.mdx)("p",null,"This guide will show you some of the most important features of Hydra.\nRead the ",(0,l.mdx)("a",{parentName:"p",href:"/docs/0.11/tutorial/simple_cli"},"tutorial")," to gain a deeper understanding."),(0,l.mdx)("h3",{id:"installation"},"Installation"),(0,l.mdx)("p",null,"Install Hydra 0.11 with ",(0,l.mdx)("inlineCode",{parentName:"p"},"pip install hydra-core --upgrade"),"."),(0,l.mdx)("h3",{id:"basic-example"},"Basic example"),(0,l.mdx)("p",null,"Configuration file: ",(0,l.mdx)("inlineCode",{parentName:"p"},"config.yaml")),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml"},"db:\n driver: mysql\n user: omry\n pass: secret\n")),(0,l.mdx)("p",null,"Python file: ",(0,l.mdx)("inlineCode",{parentName:"p"},"my_app.py")),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:"{4-6}","{4-6}":!0},'import hydra\nfrom omegaconf import DictConfig\n\n@hydra.main(config_path="config.yaml")\ndef my_app(cfg : DictConfig) -> None:\n print(OmegaConf.to_yaml(cfg))\n\nif __name__ == "__main__":\n my_app()\n')),(0,l.mdx)("p",null,"You can learn more about OmegaConf ",(0,l.mdx)("a",{parentName:"p",href:"https://omegaconf.readthedocs.io/en/latest/usage.html#access-and-manipulation"},"here")," later."),(0,l.mdx)("p",null,(0,l.mdx)("inlineCode",{parentName:"p"},"config.yaml")," is loaded automatically when you run your application"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py\ndb:\n driver: mysql\n pass: secret\n user: omry\n")),(0,l.mdx)("p",null,"You can override values in the loaded config from the command line:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{4-5}","{4-5}":!0},"$ python my_app.py db.user=root db.pass=1234\ndb:\n driver: mysql\n user: root\n pass: 1234\n")),(0,l.mdx)("h3",{id:"composition-example"},"Composition example"),(0,l.mdx)("p",null,"You may want to alternate between two different databases. To support this create a ",(0,l.mdx)("inlineCode",{parentName:"p"},"config group")," named db,\nand place one config file for each alternative inside:\nThe directory structure of our application now looks like:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-text"},"\u251c\u2500\u2500 db\n\u2502 \u251c\u2500\u2500 mysql.yaml\n\u2502 \u2514\u2500\u2500 postgresql.yaml\n\u251c\u2500\u2500 config.yaml\n\u2514\u2500\u2500 my_app.py\n")),(0,l.mdx)("p",null,"Here is the new ",(0,l.mdx)("inlineCode",{parentName:"p"},"config.yaml")),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - db: mysql\n# some other config options in your config file.\nwebsite:\n domain: example.com\n")),(0,l.mdx)("p",null,(0,l.mdx)("inlineCode",{parentName:"p"},"defaults")," is a special directive telling Hydra to use db/mysql.yaml when composing the configuration object.\nThe resulting cfg object is a composition of configs from defaults with configs specified in your ",(0,l.mdx)("inlineCode",{parentName:"p"},"config.yaml"),"."),(0,l.mdx)("p",null,"You can now choose which database configuration to use from the and override values from the command line: "),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py db=postgresql db.timeout=20\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 20\n user: postgres_user\nwebsite:\n domain: example.com\n")),(0,l.mdx)("p",null,"You can have as many config groups as you need."),(0,l.mdx)("h3",{id:"multirun"},"Multirun"),(0,l.mdx)("p",null,"You can run your function multiple times with different configuration easily with the ",(0,l.mdx)("inlineCode",{parentName:"p"},"--multirun|-m")," flag."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre"},"$ python my_app.py --multirun db=mysql,postgresql\n[HYDRA] Sweep output dir : multirun/2020-01-09/01-16-29\n[HYDRA] Launching 2 jobs locally\n[HYDRA] #0 : db=mysql\ndb:\n driver: mysql\n pass: secret\n user: omry\nwebsite:\n domain: example.com\n\n[HYDRA] #1 : db=postgresql\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 10\n user: postgres_user\nwebsite:\n domain: example.com\n")),(0,l.mdx)("p",null,"There is a whole lot more to Hydra. Read the ",(0,l.mdx)("a",{parentName:"p",href:"/docs/0.11/tutorial/simple_cli"},"tutorial")," to learn more."),(0,l.mdx)("h2",{id:"other-stuff"},"Other stuff"),(0,l.mdx)("h3",{id:"community"},"Community"),(0,l.mdx)("p",null,"Ask questions on github or StackOverflow (Use the tag #fb-hydra):"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("a",{parentName:"li",href:"https://github.com/facebookresearch/hydra/discussions"},"github")),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("a",{parentName:"li",href:"https://stackoverflow.com/questions/tagged/fb-hydra"},"StackOverflow"))),(0,l.mdx)("p",null,"Follow Hydra on Twitter and Facebook:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("a",{parentName:"li",href:"https://www.facebook.com/Hydra-Framework-109364473802509/"},"Facebook page")),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("a",{parentName:"li",href:"https://twitter.com/Hydra_Framework"},"Twitter"))),(0,l.mdx)("h3",{id:"citing-hydra"},"Citing Hydra"),(0,l.mdx)("p",null,"If you use Hydra in your research please use the following BibTeX entry:"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-text"},"@Misc{Yadan2019Hydra,\n author = {Omry Yadan},\n title = {Hydra - A framework for elegantly configuring complex applications},\n howpublished = {Github},\n year = {2019},\n url = {https://github.com/facebookresearch/hydra}\n}\n")))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2d57dfba.7564726c.js b/assets/js/2d57dfba.7564726c.js deleted file mode 100644 index 495808005c..0000000000 --- a/assets/js/2d57dfba.7564726c.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[9348],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>m,MDXProvider:()=>c,mdx:()=>f,useMDXComponents:()=>p,withMDXComponents:()=>d});var a=t(96540);function i(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function o(){return o=Object.assign||function(e){for(var n=1;n=0||(i[t]=e[t]);return i}(e,n);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(i[t]=e[t])}return i}var m=a.createContext({}),d=function(e){return function(n){var t=p(n.components);return a.createElement(e,o({},n,{components:t}))}},p=function(e){var n=a.useContext(m),t=n;return e&&(t="function"==typeof e?e(n):l(l({},n),e)),t},c=function(e){var n=p(e.components);return a.createElement(m.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},h=a.forwardRef((function(e,n){var t=e.components,i=e.mdxType,o=e.originalType,r=e.parentName,m=s(e,["components","mdxType","originalType","parentName"]),d=p(t),c=i,h=d["".concat(r,".").concat(c)]||d[c]||u[c]||o;return t?a.createElement(h,l(l({ref:n},m),{},{components:t})):a.createElement(h,l({ref:n},m))}));function f(e,n){var t=arguments,i=n&&n.mdxType;if("string"==typeof e||i){var o=t.length,r=new Array(o);r[0]=h;var l={};for(var s in n)hasOwnProperty.call(n,s)&&(l[s]=n[s]);l.originalType=e,l.mdxType="string"==typeof e?e:i,r[1]=l;for(var m=2;m{t.d(n,{A:()=>s,C:()=>m});var a=t(58168),i=t(96540),o=t(75489),r=t(44586),l=t(74098);function s(e){return i.createElement(o.default,(0,a.A)({},e,{to:(n=e.to,s=(0,l.useActiveVersion)(),(0,r.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==s?void 0:s.name)?t:"current"]+n),target:"_blank"}));var n,t,s}function m(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return i.createElement(s,e,i.createElement("span",null,"\xa0"),i.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},74118:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>m,default:()=>u,frontMatter:()=>s,metadata:()=>d,toc:()=>p});var a=t(58168),i=t(98587),o=(t(96540),t(15680)),r=t(49595),l=["components"],s={id:"compose_api",title:"Compose API",sidebar_label:"Compose API"},m=void 0,d={unversionedId:"advanced/compose_api",id:"version-1.3/advanced/compose_api",title:"Compose API",description:"The compose API can compose a config similarly to @hydra.main() anywhere in the code.",source:"@site/versioned_docs/version-1.3/advanced/compose_api.md",sourceDirName:"advanced",slug:"/advanced/compose_api",permalink:"/docs/1.3/advanced/compose_api",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/advanced/compose_api.md",tags:[],version:"1.3",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"compose_api",title:"Compose API",sidebar_label:"Compose API"},sidebar:"docs",previous:{title:"Structured Configs example",permalink:"/docs/1.3/advanced/instantiate_objects/structured_config"},next:{title:"Config Search Path",permalink:"/docs/1.3/advanced/search_path"}},p=[{value:"When to use the Compose API",id:"when-to-use-the-compose-api",children:[],level:3},{value:"Initialization methods",id:"initialization-methods",children:[],level:3},{value:"Code example",id:"code-example",children:[],level:3},{value:"API Documentation",id:"api-documentation",children:[],level:3}],c={toc:p};function u(e){var n=e.components,t=(0,i.A)(e,l);return(0,o.mdx)("wrapper",(0,a.A)({},c,t,{components:n,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"The compose API can compose a config similarly to ",(0,o.mdx)("inlineCode",{parentName:"p"},"@hydra.main()")," anywhere in the code.",(0,o.mdx)("br",{parentName:"p"}),"\n","Prior to calling compose(), you have to initialize Hydra: This can be done by using the standard ",(0,o.mdx)("inlineCode",{parentName:"p"},"@hydra.main()"),"\nor by calling one of the initialization methods listed below."),(0,o.mdx)("h3",{id:"when-to-use-the-compose-api"},"When to use the Compose API"),(0,o.mdx)("p",null,"The Compose API is useful when ",(0,o.mdx)("inlineCode",{parentName:"p"},"@hydra.main()")," is not applicable.\nFor example:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"Inside a Jupyter notebook (",(0,o.mdx)("a",{parentName:"li",href:"/docs/1.3/advanced/jupyter_notebooks"},"Example"),")"),(0,o.mdx)("li",{parentName:"ul"},"Inside a unit test (",(0,o.mdx)("a",{parentName:"li",href:"/docs/1.3/advanced/unit_testing"},"Example"),")"),(0,o.mdx)("li",{parentName:"ul"},"In parts of your application that does not have access to the command line (",(0,o.mdx)(r.A,{to:"examples/advanced/ad_hoc_composition",mdxType:"GithubLink"},"Example"),")."),(0,o.mdx)("li",{parentName:"ul"},"To compose multiple configuration objects (",(0,o.mdx)(r.A,{to:"examples/advanced/ray_example/ray_compose_example.py",mdxType:"GithubLink"},"Example with Ray"),").")),(0,o.mdx)("div",{class:"alert alert--info",role:"alert"},"Please avoid using the Compose API in cases where ",(0,o.mdx)("b",null,"@hydra.main()")," can be used. Doing so forfeits many of the benefits of Hydra (e.g., Tab completion, Multirun, Working directory management, Logging management and more)"),(0,o.mdx)("h3",{id:"initialization-methods"},"Initialization methods"),(0,o.mdx)("p",null,"There are 3 initialization methods:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)(r.A,{to:"hydra/initialize.py#L37",mdxType:"GithubLink"},"initialize()"),": Initialize with a config path relative to the caller"),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)(r.A,{to:"hydra/initialize.py#L108",mdxType:"GithubLink"},"initialize_config_module()"),": Initialize with config_module (absolute)"),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)(r.A,{to:"hydra/initialize.py#L143",mdxType:"GithubLink"},"initialize_config_dir()"),": Initialize with a config_dir on the file system (absolute)")),(0,o.mdx)("p",null,"All 3 can be used as methods or contexts.\nWhen used as methods, they are initializing Hydra globally and should only be called once.\nWhen used as contexts, they are initializing Hydra within the context can be used multiple times.\nLike ",(0,o.mdx)("b",null,"@hydra.main()")," all three support the ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.3/upgrades/version_base"},"version_base")," parameter\nto define the compatibility level to use."),(0,o.mdx)("h3",{id:"code-example"},"Code example"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'from hydra import compose, initialize\nfrom omegaconf import OmegaConf\n\nif __name__ == "__main__":\n # context initialization\n with initialize(version_base=None, config_path="conf", job_name="test_app"):\n cfg = compose(config_name="config", overrides=["db=mysql", "db.user=me"])\n print(OmegaConf.to_yaml(cfg))\n\n # global initialization\n initialize(version_base=None, config_path="conf", job_name="test_app")\n cfg = compose(config_name="config", overrides=["db=mysql", "db.user=me"])\n print(OmegaConf.to_yaml(cfg))\n')),(0,o.mdx)("h3",{id:"api-documentation"},"API Documentation"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Compose API"',title:'"Compose','API"':!0},'def compose(\n config_name: Optional[str] = None,\n overrides: List[str] = [],\n return_hydra_config: bool = False,\n) -> DictConfig:\n """\n :param config_name: the name of the config\n (usually the file name without the .yaml extension)\n :param overrides: list of overrides for config file\n :param return_hydra_config: True to return the hydra config node in the result\n :return: the composed config\n """\n')),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Relative initialization"',title:'"Relative','initialization"':!0},'def initialize(\n version_base: Optional[str],\n config_path: Optional[str] = None,\n job_name: Optional[str] = "app",\n caller_stack_depth: int = 1,\n) -> None:\n """\n Initializes Hydra and add the config_path to the config search path.\n config_path is relative to the parent of the caller.\n Hydra detects the caller type automatically at runtime.\n\n Supported callers:\n - Python scripts\n - Python modules\n - Unit tests\n - Jupyter notebooks.\n :param version_base: compatibility level to use.\n :param config_path: path relative to the parent of the caller\n :param job_name: the value for hydra.job.name (By default it is automatically detected based on the caller)\n :param caller_stack_depth: stack depth of the caller, defaults to 1 (direct caller).\n """\n')),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Initialzing with config module"',title:'"Initialzing',with:!0,config:!0,'module"':!0},'def initialize_config_module(\n config_module: str,\n version_base: Optional[str],\n job_name: str = "app"\n) -> None:\n """\n Initializes Hydra and add the config_module to the config search path.\n The config module must be importable (an __init__.py must exist at its top level)\n :param config_module: absolute module name, for example "foo.bar.conf".\n :param version_base: compatibility level to use.\n :param job_name: the value for hydra.job.name (default is \'app\')\n """\n')),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Initialzing with config directory"',title:'"Initialzing',with:!0,config:!0,'directory"':!0},'def initialize_config_dir(\n config_dir: str,\n version_base: Optional[str],\n job_name: str = "app"\n) -> None:\n """\n Initializes Hydra and add an absolute config dir to the to the config search path.\n The config_dir is always a path on the file system and is must be an absolute path.\n Relative paths will result in an error.\n :param config_dir: absolute file system path\n :param version_base: compatibility level to use.\n :param job_name: the value for hydra.job.name (default is \'app\')\n """\n')))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2d57dfba.b98ceae8.js b/assets/js/2d57dfba.b98ceae8.js new file mode 100644 index 0000000000..23040a2470 --- /dev/null +++ b/assets/js/2d57dfba.b98ceae8.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[9348],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>m,MDXProvider:()=>c,mdx:()=>f,useMDXComponents:()=>p,withMDXComponents:()=>d});var a=t(96540);function i(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function o(){return o=Object.assign||function(e){for(var n=1;n=0||(i[t]=e[t]);return i}(e,n);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(i[t]=e[t])}return i}var m=a.createContext({}),d=function(e){return function(n){var t=p(n.components);return a.createElement(e,o({},n,{components:t}))}},p=function(e){var n=a.useContext(m),t=n;return e&&(t="function"==typeof e?e(n):l(l({},n),e)),t},c=function(e){var n=p(e.components);return a.createElement(m.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},h=a.forwardRef((function(e,n){var t=e.components,i=e.mdxType,o=e.originalType,r=e.parentName,m=s(e,["components","mdxType","originalType","parentName"]),d=p(t),c=i,h=d["".concat(r,".").concat(c)]||d[c]||u[c]||o;return t?a.createElement(h,l(l({ref:n},m),{},{components:t})):a.createElement(h,l({ref:n},m))}));function f(e,n){var t=arguments,i=n&&n.mdxType;if("string"==typeof e||i){var o=t.length,r=new Array(o);r[0]=h;var l={};for(var s in n)hasOwnProperty.call(n,s)&&(l[s]=n[s]);l.originalType=e,l.mdxType="string"==typeof e?e:i,r[1]=l;for(var m=2;m{t.d(n,{A:()=>s,C:()=>m});var a=t(58168),i=t(96540),o=t(75489),r=t(44586),l=t(74098);function s(e){return i.createElement(o.default,(0,a.A)({},e,{to:(n=e.to,s=(0,l.useActiveVersion)(),(0,r.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==s?void 0:s.name)?t:"current"]+n),target:"_blank"}));var n,t,s}function m(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return i.createElement(s,e,i.createElement("span",null,"\xa0"),i.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},74118:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>m,default:()=>u,frontMatter:()=>s,metadata:()=>d,toc:()=>p});var a=t(58168),i=t(98587),o=(t(96540),t(15680)),r=t(49595),l=["components"],s={id:"compose_api",title:"Compose API",sidebar_label:"Compose API"},m=void 0,d={unversionedId:"advanced/compose_api",id:"version-1.3/advanced/compose_api",title:"Compose API",description:"The compose API can compose a config similarly to @hydra.main() anywhere in the code.",source:"@site/versioned_docs/version-1.3/advanced/compose_api.md",sourceDirName:"advanced",slug:"/advanced/compose_api",permalink:"/docs/1.3/advanced/compose_api",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/advanced/compose_api.md",tags:[],version:"1.3",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"compose_api",title:"Compose API",sidebar_label:"Compose API"},sidebar:"docs",previous:{title:"Structured Configs example",permalink:"/docs/1.3/advanced/instantiate_objects/structured_config"},next:{title:"Config Search Path",permalink:"/docs/1.3/advanced/search_path"}},p=[{value:"When to use the Compose API",id:"when-to-use-the-compose-api",children:[],level:3},{value:"Initialization methods",id:"initialization-methods",children:[],level:3},{value:"Code example",id:"code-example",children:[],level:3},{value:"API Documentation",id:"api-documentation",children:[],level:3}],c={toc:p};function u(e){var n=e.components,t=(0,i.A)(e,l);return(0,o.mdx)("wrapper",(0,a.A)({},c,t,{components:n,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"The compose API can compose a config similarly to ",(0,o.mdx)("inlineCode",{parentName:"p"},"@hydra.main()")," anywhere in the code.",(0,o.mdx)("br",{parentName:"p"}),"\n","Prior to calling compose(), you have to initialize Hydra: This can be done by using the standard ",(0,o.mdx)("inlineCode",{parentName:"p"},"@hydra.main()"),"\nor by calling one of the initialization methods listed below."),(0,o.mdx)("h3",{id:"when-to-use-the-compose-api"},"When to use the Compose API"),(0,o.mdx)("p",null,"The Compose API is useful when ",(0,o.mdx)("inlineCode",{parentName:"p"},"@hydra.main()")," is not applicable.\nFor example:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"Inside a Jupyter notebook (",(0,o.mdx)("a",{parentName:"li",href:"/docs/1.3/advanced/jupyter_notebooks"},"Example"),")"),(0,o.mdx)("li",{parentName:"ul"},"Inside a unit test (",(0,o.mdx)("a",{parentName:"li",href:"/docs/1.3/advanced/unit_testing"},"Example"),")"),(0,o.mdx)("li",{parentName:"ul"},"In parts of your application that does not have access to the command line (",(0,o.mdx)(r.A,{to:"examples/advanced/ad_hoc_composition",mdxType:"GithubLink"},"Example"),")."),(0,o.mdx)("li",{parentName:"ul"},"To compose multiple configuration objects (",(0,o.mdx)(r.A,{to:"examples/advanced/ray_example/ray_compose_example.py",mdxType:"GithubLink"},"Example with Ray"),").")),(0,o.mdx)("div",{class:"alert alert--info",role:"alert"},"Please avoid using the Compose API in cases where ",(0,o.mdx)("b",null,"@hydra.main()")," can be used. Doing so forfeits many of the benefits of Hydra (e.g., Tab completion, Multirun, Working directory management, Logging management and more)"),(0,o.mdx)("h3",{id:"initialization-methods"},"Initialization methods"),(0,o.mdx)("p",null,"There are 3 initialization methods:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)(r.A,{to:"hydra/initialize.py#L37",mdxType:"GithubLink"},"initialize()"),": Initialize with a config path relative to the caller"),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)(r.A,{to:"hydra/initialize.py#L108",mdxType:"GithubLink"},"initialize_config_module()"),": Initialize with config_module (absolute)"),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)(r.A,{to:"hydra/initialize.py#L143",mdxType:"GithubLink"},"initialize_config_dir()"),": Initialize with a config_dir on the file system (absolute)")),(0,o.mdx)("p",null,"All 3 can be used as methods or contexts.\nWhen used as methods, they are initializing Hydra globally and should only be called once.\nWhen used as contexts, they are initializing Hydra within the context can be used multiple times.\nLike ",(0,o.mdx)("b",null,"@hydra.main()")," all three support the ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.3/upgrades/version_base"},"version_base")," parameter\nto define the compatibility level to use."),(0,o.mdx)("h3",{id:"code-example"},"Code example"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python"},'from hydra import compose, initialize\nfrom omegaconf import OmegaConf\n\nif __name__ == "__main__":\n # context initialization\n with initialize(version_base=None, config_path="conf", job_name="test_app"):\n cfg = compose(config_name="config", overrides=["db=mysql", "db.user=me"])\n print(OmegaConf.to_yaml(cfg))\n\n # global initialization\n initialize(version_base=None, config_path="conf", job_name="test_app")\n cfg = compose(config_name="config", overrides=["db=mysql", "db.user=me"])\n print(OmegaConf.to_yaml(cfg))\n')),(0,o.mdx)("h3",{id:"api-documentation"},"API Documentation"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Compose API"',title:'"Compose','API"':!0},'def compose(\n config_name: Optional[str] = None,\n overrides: List[str] = [],\n return_hydra_config: bool = False,\n) -> DictConfig:\n """\n :param config_name: the name of the config\n (usually the file name without the .yaml extension)\n :param overrides: list of overrides for config file\n :param return_hydra_config: True to return the hydra config node in the result\n :return: the composed config\n """\n')),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Relative initialization"',title:'"Relative','initialization"':!0},'def initialize(\n version_base: Optional[str],\n config_path: Optional[str] = None,\n job_name: Optional[str] = "app",\n caller_stack_depth: int = 1,\n) -> None:\n """\n Initializes Hydra and add the config_path to the config search path.\n config_path is relative to the parent of the caller.\n Hydra detects the caller type automatically at runtime.\n\n Supported callers:\n - Python scripts\n - Python modules\n - Unit tests\n - Jupyter notebooks.\n :param version_base: compatibility level to use.\n :param config_path: path relative to the parent of the caller\n :param job_name: the value for hydra.job.name (By default it is automatically detected based on the caller)\n :param caller_stack_depth: stack depth of the caller, defaults to 1 (direct caller).\n """\n')),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Initialzing with config module"',title:'"Initialzing',with:!0,config:!0,'module"':!0},'def initialize_config_module(\n config_module: str,\n version_base: Optional[str],\n job_name: str = "app"\n) -> None:\n """\n Initializes Hydra and add the config_module to the config search path.\n The config module must be importable (an __init__.py must exist at its top level)\n :param config_module: absolute module name, for example "foo.bar.conf".\n :param version_base: compatibility level to use.\n :param job_name: the value for hydra.job.name (default is \'app\')\n """\n')),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Initialzing with config directory"',title:'"Initialzing',with:!0,config:!0,'directory"':!0},'def initialize_config_dir(\n config_dir: str,\n version_base: Optional[str],\n job_name: str = "app"\n) -> None:\n """\n Initializes Hydra and add an absolute config dir to the to the config search path.\n The config_dir is always a path on the file system and is must be an absolute path.\n Relative paths will result in an error.\n :param config_dir: absolute file system path\n :param version_base: compatibility level to use.\n :param job_name: the value for hydra.job.name (default is \'app\')\n """\n')))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2e99c05e.1f660925.js b/assets/js/2e99c05e.1f660925.js new file mode 100644 index 0000000000..39be7756fb --- /dev/null +++ b/assets/js/2e99c05e.1f660925.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[8661],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>p,MDXProvider:()=>m,mdx:()=>f,useMDXComponents:()=>s,withMDXComponents:()=>c});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(){return i=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var p=r.createContext({}),c=function(e){return function(t){var n=s(t.components);return r.createElement(e,i({},t,{components:n}))}},s=function(e){var t=r.useContext(p),n=t;return e&&(n="function"==typeof e?e(t):a(a({},t),e)),n},m=function(e){var t=s(e.components);return r.createElement(p.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},y=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,i=e.originalType,l=e.parentName,p=d(e,["components","mdxType","originalType","parentName"]),c=s(n),m=o,y=c["".concat(l,".").concat(m)]||c[m]||u[m]||i;return n?r.createElement(y,a(a({ref:t},p),{},{components:n})):r.createElement(y,a({ref:t},p))}));function f(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var i=n.length,l=new Array(i);l[0]=y;var a={};for(var d in t)hasOwnProperty.call(t,d)&&(a[d]=t[d]);a.originalType=e,a.mdxType="string"==typeof e?e:o,l[1]=a;for(var p=2;p{n.r(t),n.d(t,{contentTitle:()=>d,default:()=>m,frontMatter:()=>a,metadata:()=>p,toc:()=>c});var r=n(58168),o=n(98587),i=(n(96540),n(15680)),l=["components"],a={id:"style_guide",title:"Style Guide",sidebar_label:"Style Guide"},d=void 0,p={unversionedId:"development/style_guide",id:"development/style_guide",title:"Style Guide",description:"The code need to pass verification by the following tools:",source:"@site/docs/development/style_guide.md",sourceDirName:"development",slug:"/development/style_guide",permalink:"/docs/development/style_guide",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/development/style_guide.md",tags:[],version:"current",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"style_guide",title:"Style Guide",sidebar_label:"Style Guide"},sidebar:"docs",previous:{title:"Testing",permalink:"/docs/development/testing"},next:{title:"Documentation",permalink:"/docs/development/documentation"}},c=[],s={toc:c};function m(e){var t=e.components,n=(0,o.A)(e,l);return(0,i.mdx)("wrapper",(0,r.A)({},s,n,{components:t,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"The code need to pass verification by the following tools:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"black .")," : Automatic code formatting for Python"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"flake8")," : PEP8 compliance checker for Python, this includes copyright header verification"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"isort .")," : Ensure imports are sorted properly"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"mypy --strict .")," : Ensures code passes strict type checking"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"yamllint .")," : Ensures that yaml files are syntactically correct and properly indented.")),(0,i.mdx)("p",null,"The easiest way to run the required verifications is: "),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"nox -s lint")," : for the Hydra core"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"nox -s lint_plugins")," : for the included plugins")),(0,i.mdx)("p",null,"isort is a bit tricky to run for plugins. the best way to get it to sort the plugins imports is with the FIX environment\nvariable:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre"},"$ FIX=1 nox -s lint_plugins\n")),(0,i.mdx)("p",null,"It is also recommended that you install pre-commit hooks (use ",(0,i.mdx)("inlineCode",{parentName:"p"},"pre-commit install"),").\npre-commit will execute some of the above tests when you commit your code locally.\nYou can disable it by appending ",(0,i.mdx)("inlineCode",{parentName:"p"},"-n")," to your commit command: ",(0,i.mdx)("inlineCode",{parentName:"p"},"git commit -m wip -n")),(0,i.mdx)("p",null,"Pull requests that do not lint will fail the automated testing."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2e99c05e.fd17efb6.js b/assets/js/2e99c05e.fd17efb6.js deleted file mode 100644 index 9f1ed1eb1b..0000000000 --- a/assets/js/2e99c05e.fd17efb6.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[8661],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>p,MDXProvider:()=>m,mdx:()=>f,useMDXComponents:()=>s,withMDXComponents:()=>c});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(){return i=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var p=r.createContext({}),c=function(e){return function(t){var n=s(t.components);return r.createElement(e,i({},t,{components:n}))}},s=function(e){var t=r.useContext(p),n=t;return e&&(n="function"==typeof e?e(t):a(a({},t),e)),n},m=function(e){var t=s(e.components);return r.createElement(p.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},y=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,i=e.originalType,l=e.parentName,p=d(e,["components","mdxType","originalType","parentName"]),c=s(n),m=o,y=c["".concat(l,".").concat(m)]||c[m]||u[m]||i;return n?r.createElement(y,a(a({ref:t},p),{},{components:n})):r.createElement(y,a({ref:t},p))}));function f(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var i=n.length,l=new Array(i);l[0]=y;var a={};for(var d in t)hasOwnProperty.call(t,d)&&(a[d]=t[d]);a.originalType=e,a.mdxType="string"==typeof e?e:o,l[1]=a;for(var p=2;p{n.r(t),n.d(t,{contentTitle:()=>d,default:()=>m,frontMatter:()=>a,metadata:()=>p,toc:()=>c});var r=n(58168),o=n(98587),i=(n(96540),n(15680)),l=["components"],a={id:"style_guide",title:"Style Guide",sidebar_label:"Style Guide"},d=void 0,p={unversionedId:"development/style_guide",id:"development/style_guide",title:"Style Guide",description:"The code need to pass verification by the following tools:",source:"@site/docs/development/style_guide.md",sourceDirName:"development",slug:"/development/style_guide",permalink:"/docs/development/style_guide",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/development/style_guide.md",tags:[],version:"current",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"style_guide",title:"Style Guide",sidebar_label:"Style Guide"},sidebar:"docs",previous:{title:"Testing",permalink:"/docs/development/testing"},next:{title:"Documentation",permalink:"/docs/development/documentation"}},c=[],s={toc:c};function m(e){var t=e.components,n=(0,o.A)(e,l);return(0,i.mdx)("wrapper",(0,r.A)({},s,n,{components:t,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"The code need to pass verification by the following tools:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"black .")," : Automatic code formatting for Python"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"flake8")," : PEP8 compliance checker for Python, this includes copyright header verification"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"isort .")," : Ensure imports are sorted properly"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"mypy --strict .")," : Ensures code passes strict type checking"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"yamllint .")," : Ensures that yaml files are syntactically correct and properly indented.")),(0,i.mdx)("p",null,"The easiest way to run the required verifications is: "),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"nox -s lint")," : for the Hydra core"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"nox -s lint_plugins")," : for the included plugins")),(0,i.mdx)("p",null,"isort is a bit tricky to run for plugins. the best way to get it to sort the plugins imports is with the FIX environment\nvariable:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre"},"$ FIX=1 nox -s lint_plugins\n")),(0,i.mdx)("p",null,"It is also recommended that you install pre-commit hooks (use ",(0,i.mdx)("inlineCode",{parentName:"p"},"pre-commit install"),").\npre-commit will execute some of the above tests when you commit your code locally.\nYou can disable it by appending ",(0,i.mdx)("inlineCode",{parentName:"p"},"-n")," to your commit command: ",(0,i.mdx)("inlineCode",{parentName:"p"},"git commit -m wip -n")),(0,i.mdx)("p",null,"Pull requests that do not lint will fail the automated testing."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2f529812.21a66089.js b/assets/js/2f529812.21a66089.js new file mode 100644 index 0000000000..1a8babef29 --- /dev/null +++ b/assets/js/2f529812.21a66089.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[2492],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>p,MDXProvider:()=>u,mdx:()=>y,useMDXComponents:()=>m,withMDXComponents:()=>d});var r=t(96540);function o(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function a(){return a=Object.assign||function(e){for(var n=1;n=0||(o[t]=e[t]);return o}(e,n);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(o[t]=e[t])}return o}var p=r.createContext({}),d=function(e){return function(n){var t=m(n.components);return r.createElement(e,a({},n,{components:t}))}},m=function(e){var n=r.useContext(p),t=n;return e&&(t="function"==typeof e?e(n):l(l({},n),e)),t},u=function(e){var n=m(e.components);return r.createElement(p.Provider,{value:n},e.children)},s={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},c=r.forwardRef((function(e,n){var t=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,p=g(e,["components","mdxType","originalType","parentName"]),d=m(t),u=o,c=d["".concat(i,".").concat(u)]||d[u]||s[u]||a;return t?r.createElement(c,l(l({ref:n},p),{},{components:t})):r.createElement(c,l({ref:n},p))}));function y(e,n){var t=arguments,o=n&&n.mdxType;if("string"==typeof e||o){var a=t.length,i=new Array(a);i[0]=c;var l={};for(var g in n)hasOwnProperty.call(n,g)&&(l[g]=n[g]);l.originalType=e,l.mdxType="string"==typeof e?e:o,i[1]=l;for(var p=2;p{t.d(n,{A:()=>g,C:()=>p});var r=t(58168),o=t(96540),a=t(75489),i=t(44586),l=t(74098);function g(e){return o.createElement(a.default,(0,r.A)({},e,{to:(n=e.to,g=(0,l.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==g?void 0:g.name)?t:"current"]+n),target:"_blank"}));var n,t,g}function p(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return o.createElement(g,e,o.createElement("span",null,"\xa0"),o.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},12701:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>p,default:()=>s,frontMatter:()=>g,metadata:()=>d,toc:()=>m});var r=t(58168),o=t(98587),a=(t(96540),t(15680)),i=t(49595),l=["components"],g={id:"logging",title:"Logging",sidebar_label:"Logging"},p=void 0,d={unversionedId:"tutorials/basic/running_your_app/logging",id:"tutorials/basic/running_your_app/logging",title:"Logging",description:"People often do not use Python logging due to the setup cost.",source:"@site/docs/tutorials/basic/running_your_app/4_logging.md",sourceDirName:"tutorials/basic/running_your_app",slug:"/tutorials/basic/running_your_app/logging",permalink:"/docs/tutorials/basic/running_your_app/logging",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/tutorials/basic/running_your_app/4_logging.md",tags:[],version:"current",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:4,frontMatter:{id:"logging",title:"Logging",sidebar_label:"Logging"},sidebar:"docs",previous:{title:"Output/Working directory",permalink:"/docs/tutorials/basic/running_your_app/working_directory"},next:{title:"Debugging",permalink:"/docs/tutorials/basic/running_your_app/debugging"}},m=[],u={toc:m};function s(e){var n=e.components,t=(0,o.A)(e,l);return(0,a.mdx)("wrapper",(0,r.A)({},u,t,{components:n,mdxType:"MDXLayout"}),(0,a.mdx)(i.C,{to:"examples/tutorials/basic/running_your_hydra_app/4_logging/my_app.py",mdxType:"ExampleGithubLink"}),(0,a.mdx)("p",null,"People often do not use Python logging due to the setup cost.\nHydra solves this by configuring the Python logging for you."),(0,a.mdx)("p",null,"By default, Hydra logs at the INFO level to both the console and a log file in the automatic working directory."),(0,a.mdx)("p",null,"An example of logging with Hydra:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python"},'import logging\nfrom omegaconf import DictConfig\nimport hydra\n\n# A logger for this file\nlog = logging.getLogger(__name__)\n\n@hydra.main()\ndef my_app(_cfg: DictConfig) -> None:\n log.info("Info level message")\n log.debug("Debug level message")\n\nif __name__ == "__main__":\n my_app()\n\n$ python my_app.py\n[2019-06-27 00:52:46,653][__main__][INFO] - Info level message\n\n')),(0,a.mdx)("p",null,"You can enable DEBUG level logging from the command line by overriding ",(0,a.mdx)("inlineCode",{parentName:"p"},"hydra.verbose"),"."),(0,a.mdx)("p",null,(0,a.mdx)("inlineCode",{parentName:"p"},"hydra.verbose")," can be a Boolean, a String or a List:"),(0,a.mdx)("p",null,"Examples:"),(0,a.mdx)("ul",null,(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"hydra.verbose=true")," : Sets the log level of ",(0,a.mdx)("strong",{parentName:"li"},"all")," loggers to ",(0,a.mdx)("inlineCode",{parentName:"li"},"DEBUG")),(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"hydra.verbose=NAME")," : Sets the log level of the logger ",(0,a.mdx)("inlineCode",{parentName:"li"},"NAME")," to ",(0,a.mdx)("inlineCode",{parentName:"li"},"DEBUG"),".\nEquivalent to ",(0,a.mdx)("inlineCode",{parentName:"li"},"import logging; logging.getLogger(NAME).setLevel(logging.DEBUG)"),"."),(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"hydra.verbose=[NAME1,NAME2]"),": Sets the log level of the loggers ",(0,a.mdx)("inlineCode",{parentName:"li"},"NAME1")," and ",(0,a.mdx)("inlineCode",{parentName:"li"},"NAME2")," to ",(0,a.mdx)("inlineCode",{parentName:"li"},"DEBUG"))),(0,a.mdx)("p",null,"Example output:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text"},"$ python my_app.py hydra.verbose=[__main__,hydra]\n[2019-09-29 13:06:00,880] - Installed Hydra Plugins\n[2019-09-29 13:06:00,880] - ***********************\n...\n[2019-09-29 13:06:00,896][__main__][INFO] - Info level message\n[2019-09-29 13:06:00,896][__main__][DEBUG] - Debug level message\n")),(0,a.mdx)("p",null,"You can disable the logging output by setting ",(0,a.mdx)("inlineCode",{parentName:"p"},"hydra/job_logging")," to ",(0,a.mdx)("inlineCode",{parentName:"p"},"disabled")," "),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ python my_app.py hydra/job_logging=disabled\n\n")),(0,a.mdx)("p",null,"You can also set ",(0,a.mdx)("inlineCode",{parentName:"p"},"hydra/job_logging=none")," and ",(0,a.mdx)("inlineCode",{parentName:"p"},"hydra/hydra_logging=none")," if you do not want Hydra to configure the logging."),(0,a.mdx)("p",null,"Logging can be ",(0,a.mdx)("a",{parentName:"p",href:"/docs/configure_hydra/logging"},"customized"),"."))}s.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2f529812.766dcf73.js b/assets/js/2f529812.766dcf73.js deleted file mode 100644 index ea72e44207..0000000000 --- a/assets/js/2f529812.766dcf73.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[2492],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>p,MDXProvider:()=>u,mdx:()=>y,useMDXComponents:()=>m,withMDXComponents:()=>d});var r=t(96540);function o(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function a(){return a=Object.assign||function(e){for(var n=1;n=0||(o[t]=e[t]);return o}(e,n);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(o[t]=e[t])}return o}var p=r.createContext({}),d=function(e){return function(n){var t=m(n.components);return r.createElement(e,a({},n,{components:t}))}},m=function(e){var n=r.useContext(p),t=n;return e&&(t="function"==typeof e?e(n):l(l({},n),e)),t},u=function(e){var n=m(e.components);return r.createElement(p.Provider,{value:n},e.children)},s={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},c=r.forwardRef((function(e,n){var t=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,p=g(e,["components","mdxType","originalType","parentName"]),d=m(t),u=o,c=d["".concat(i,".").concat(u)]||d[u]||s[u]||a;return t?r.createElement(c,l(l({ref:n},p),{},{components:t})):r.createElement(c,l({ref:n},p))}));function y(e,n){var t=arguments,o=n&&n.mdxType;if("string"==typeof e||o){var a=t.length,i=new Array(a);i[0]=c;var l={};for(var g in n)hasOwnProperty.call(n,g)&&(l[g]=n[g]);l.originalType=e,l.mdxType="string"==typeof e?e:o,i[1]=l;for(var p=2;p{t.d(n,{A:()=>g,C:()=>p});var r=t(58168),o=t(96540),a=t(75489),i=t(44586),l=t(74098);function g(e){return o.createElement(a.default,(0,r.A)({},e,{to:(n=e.to,g=(0,l.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==g?void 0:g.name)?t:"current"]+n),target:"_blank"}));var n,t,g}function p(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return o.createElement(g,e,o.createElement("span",null,"\xa0"),o.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},12701:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>p,default:()=>s,frontMatter:()=>g,metadata:()=>d,toc:()=>m});var r=t(58168),o=t(98587),a=(t(96540),t(15680)),i=t(49595),l=["components"],g={id:"logging",title:"Logging",sidebar_label:"Logging"},p=void 0,d={unversionedId:"tutorials/basic/running_your_app/logging",id:"tutorials/basic/running_your_app/logging",title:"Logging",description:"People often do not use Python logging due to the setup cost.",source:"@site/docs/tutorials/basic/running_your_app/4_logging.md",sourceDirName:"tutorials/basic/running_your_app",slug:"/tutorials/basic/running_your_app/logging",permalink:"/docs/tutorials/basic/running_your_app/logging",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/tutorials/basic/running_your_app/4_logging.md",tags:[],version:"current",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:4,frontMatter:{id:"logging",title:"Logging",sidebar_label:"Logging"},sidebar:"docs",previous:{title:"Output/Working directory",permalink:"/docs/tutorials/basic/running_your_app/working_directory"},next:{title:"Debugging",permalink:"/docs/tutorials/basic/running_your_app/debugging"}},m=[],u={toc:m};function s(e){var n=e.components,t=(0,o.A)(e,l);return(0,a.mdx)("wrapper",(0,r.A)({},u,t,{components:n,mdxType:"MDXLayout"}),(0,a.mdx)(i.C,{to:"examples/tutorials/basic/running_your_hydra_app/4_logging/my_app.py",mdxType:"ExampleGithubLink"}),(0,a.mdx)("p",null,"People often do not use Python logging due to the setup cost.\nHydra solves this by configuring the Python logging for you."),(0,a.mdx)("p",null,"By default, Hydra logs at the INFO level to both the console and a log file in the automatic working directory."),(0,a.mdx)("p",null,"An example of logging with Hydra:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python"},'import logging\nfrom omegaconf import DictConfig\nimport hydra\n\n# A logger for this file\nlog = logging.getLogger(__name__)\n\n@hydra.main()\ndef my_app(_cfg: DictConfig) -> None:\n log.info("Info level message")\n log.debug("Debug level message")\n\nif __name__ == "__main__":\n my_app()\n\n$ python my_app.py\n[2019-06-27 00:52:46,653][__main__][INFO] - Info level message\n\n')),(0,a.mdx)("p",null,"You can enable DEBUG level logging from the command line by overriding ",(0,a.mdx)("inlineCode",{parentName:"p"},"hydra.verbose"),"."),(0,a.mdx)("p",null,(0,a.mdx)("inlineCode",{parentName:"p"},"hydra.verbose")," can be a Boolean, a String or a List:"),(0,a.mdx)("p",null,"Examples:"),(0,a.mdx)("ul",null,(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"hydra.verbose=true")," : Sets the log level of ",(0,a.mdx)("strong",{parentName:"li"},"all")," loggers to ",(0,a.mdx)("inlineCode",{parentName:"li"},"DEBUG")),(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"hydra.verbose=NAME")," : Sets the log level of the logger ",(0,a.mdx)("inlineCode",{parentName:"li"},"NAME")," to ",(0,a.mdx)("inlineCode",{parentName:"li"},"DEBUG"),".\nEquivalent to ",(0,a.mdx)("inlineCode",{parentName:"li"},"import logging; logging.getLogger(NAME).setLevel(logging.DEBUG)"),"."),(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"hydra.verbose=[NAME1,NAME2]"),": Sets the log level of the loggers ",(0,a.mdx)("inlineCode",{parentName:"li"},"NAME1")," and ",(0,a.mdx)("inlineCode",{parentName:"li"},"NAME2")," to ",(0,a.mdx)("inlineCode",{parentName:"li"},"DEBUG"))),(0,a.mdx)("p",null,"Example output:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text"},"$ python my_app.py hydra.verbose=[__main__,hydra]\n[2019-09-29 13:06:00,880] - Installed Hydra Plugins\n[2019-09-29 13:06:00,880] - ***********************\n...\n[2019-09-29 13:06:00,896][__main__][INFO] - Info level message\n[2019-09-29 13:06:00,896][__main__][DEBUG] - Debug level message\n")),(0,a.mdx)("p",null,"You can disable the logging output by setting ",(0,a.mdx)("inlineCode",{parentName:"p"},"hydra/job_logging")," to ",(0,a.mdx)("inlineCode",{parentName:"p"},"disabled")," "),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-commandline"},"$ python my_app.py hydra/job_logging=disabled\n\n")),(0,a.mdx)("p",null,"You can also set ",(0,a.mdx)("inlineCode",{parentName:"p"},"hydra/job_logging=none")," and ",(0,a.mdx)("inlineCode",{parentName:"p"},"hydra/hydra_logging=none")," if you do not want Hydra to configure the logging."),(0,a.mdx)("p",null,"Logging can be ",(0,a.mdx)("a",{parentName:"p",href:"/docs/configure_hydra/logging"},"customized"),"."))}s.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/315f70d7.4e8a65f3.js b/assets/js/315f70d7.4e8a65f3.js deleted file mode 100644 index 3b55309a96..0000000000 --- a/assets/js/315f70d7.4e8a65f3.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[6448],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>p,MDXProvider:()=>u,mdx:()=>f,useMDXComponents:()=>s,withMDXComponents:()=>m});var r=n(96540);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var p=r.createContext({}),m=function(e){return function(t){var n=s(t.components);return r.createElement(e,a({},t,{components:n}))}},s=function(e){var t=r.useContext(p),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},u=function(e){var t=s(e.components);return r.createElement(p.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},y=r.forwardRef((function(e,t){var n=e.components,i=e.mdxType,a=e.originalType,o=e.parentName,p=c(e,["components","mdxType","originalType","parentName"]),m=s(n),u=i,y=m["".concat(o,".").concat(u)]||m[u]||d[u]||a;return n?r.createElement(y,l(l({ref:t},p),{},{components:n})):r.createElement(y,l({ref:t},p))}));function f(e,t){var n=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var a=n.length,o=new Array(a);o[0]=y;var l={};for(var c in t)hasOwnProperty.call(t,c)&&(l[c]=t[c]);l.originalType=e,l.mdxType="string"==typeof e?e:i,o[1]=l;for(var p=2;p{n.d(t,{A:()=>c,C:()=>p});var r=n(58168),i=n(96540),a=n(75489),o=n(44586),l=n(74098);function c(e){return i.createElement(a.default,(0,r.A)({},e,{to:(t=e.to,c=(0,l.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==c?void 0:c.name)?n:"current"]+t),target:"_blank"}));var t,n,c}function p(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return i.createElement(c,e,i.createElement("span",null,"\xa0"),i.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},84358:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>p,default:()=>d,frontMatter:()=>c,metadata:()=>m,toc:()=>s});var r=n(58168),i=n(98587),a=(n(96540),n(15680)),o=n(49595),l=["components"],c={id:"minimal_example",title:"Minimal example"},p=void 0,m={unversionedId:"tutorials/structured_config/minimal_example",id:"version-1.2/tutorials/structured_config/minimal_example",title:"Minimal example",description:"There are four key elements in this example:",source:"@site/versioned_docs/version-1.2/tutorials/structured_config/1_minimal_example.md",sourceDirName:"tutorials/structured_config",slug:"/tutorials/structured_config/minimal_example",permalink:"/docs/1.2/tutorials/structured_config/minimal_example",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/tutorials/structured_config/1_minimal_example.md",tags:[],version:"1.2",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:1,frontMatter:{id:"minimal_example",title:"Minimal example"},sidebar:"docs",previous:{title:"Config Store API",permalink:"/docs/1.2/tutorials/structured_config/config_store"},next:{title:"A hierarchical static configuration",permalink:"/docs/1.2/tutorials/structured_config/hierarchical_static_config"}},s=[{value:"Duck-typing enables static type checking",id:"duck-typing-enables-static-type-checking",children:[],level:3},{value:"Structured Configs enable Hydra to catch type errors at runtime",id:"structured-configs-enable-hydra-to-catch-type-errors-at-runtime",children:[],level:3},{value:"Duck typing",id:"duck-typing",children:[],level:2}],u={toc:s};function d(e){var t=e.components,n=(0,i.A)(e,l);return(0,a.mdx)("wrapper",(0,r.A)({},u,n,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)(o.C,{to:"examples/tutorials/structured_configs/1_minimal",mdxType:"ExampleGithubLink"}),(0,a.mdx)("p",null,"There are four key elements in this example:"),(0,a.mdx)("ul",null,(0,a.mdx)("li",{parentName:"ul"},"A ",(0,a.mdx)("inlineCode",{parentName:"li"},"@dataclass")," describes the application's configuration"),(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"ConfigStore")," manages the Structured Config"),(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"cfg")," is ",(0,a.mdx)("inlineCode",{parentName:"li"},"duck typed")," as a ",(0,a.mdx)("inlineCode",{parentName:"li"},"MySQLConfig")," instead of a ",(0,a.mdx)("inlineCode",{parentName:"li"},"DictConfig")),(0,a.mdx)("li",{parentName:"ul"},"There is a subtle typo in the code below, can you spot it?")),(0,a.mdx)("p",null,"In this example, the config node stored in the ",(0,a.mdx)("inlineCode",{parentName:"p"},"ConfigStore")," replaces the traditional ",(0,a.mdx)("inlineCode",{parentName:"p"},"config.yaml")," file."),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app_type_error.py" {18}',title:'"my_app_type_error.py"',"{18}":!0},'from dataclasses import dataclass\n\nimport hydra\nfrom hydra.core.config_store import ConfigStore\n\n@dataclass\nclass MySQLConfig:\n host: str = "localhost"\n port: int = 3306\n\ncs = ConfigStore.instance()\n# Registering the Config class with the name \'config\'.\ncs.store(name="config", node=MySQLConfig)\n\n@hydra.main(version_base=None, config_name="config")\ndef my_app(cfg: MySQLConfig) -> None:\n # pork should be port!\n if cfg.pork == 80:\n print("Is this a webserver?!")\n\nif __name__ == "__main__":\n my_app()\n')),(0,a.mdx)("h3",{id:"duck-typing-enables-static-type-checking"},"Duck-typing enables static type checking"),(0,a.mdx)("p",null,"Duck-typing the config object as ",(0,a.mdx)("inlineCode",{parentName:"p"},"MySQLConfig")," enables static type checkers like ",(0,a.mdx)("inlineCode",{parentName:"p"},"mypy")," to catch\ntype errors before you run your code:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="$ mypy my_app_type_error.py"',title:'"$',mypy:!0,'my_app_type_error.py"':!0},'my_app_type_error.py:22: error: "MySQLConfig" has no attribute "pork"\nFound 1 error in 1 file (checked 1 source file)\n')),(0,a.mdx)("h3",{id:"structured-configs-enable-hydra-to-catch-type-errors-at-runtime"},"Structured Configs enable Hydra to catch type errors at runtime"),(0,a.mdx)("p",null,"If you forget to run ",(0,a.mdx)("inlineCode",{parentName:"p"},"mypy"),", Hydra will report the error at runtime:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="$ python my_app_type_error.py"',title:'"$',python:!0,'my_app_type_error.py"':!0},"Traceback (most recent call last):\n File \"my_app_type_error.py\", line 22, in my_app\n if cfg.pork == 80:\nomegaconf.errors.ConfigAttributeError: Key 'pork' not in 'MySQLConfig'\n full_key: pork\n object_type=MySQLConfig\n\nSet the environment variable HYDRA_FULL_ERROR=1 for a complete stack trace.\n")),(0,a.mdx)("p",null,"Hydra will also catch typos, or type errors in the command line:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre"},"$ python my_app_type_error.py port=fail\nError merging override port=fail\nValue 'fail' could not be converted to Integer\n full_key: port\n object_type=MySQLConfig\n")),(0,a.mdx)("p",null,"We will see additional types of runtime errors that Hydra can catch later in this tutorial. Such as:"),(0,a.mdx)("ul",null,(0,a.mdx)("li",{parentName:"ul"},"Trying to read or write a non existent field in your config object"),(0,a.mdx)("li",{parentName:"ul"},"Assigning a value that is incompatible with the declared type"),(0,a.mdx)("li",{parentName:"ul"},"Attempting to modify a ",(0,a.mdx)("a",{parentName:"li",href:"https://omegaconf.readthedocs.io/en/latest/structured_config.html#frozen"},"frozen config"))),(0,a.mdx)("h2",{id:"duck-typing"},"Duck typing"),(0,a.mdx)("p",null,"In the example above ",(0,a.mdx)("inlineCode",{parentName:"p"},"cfg")," is duck typed as ",(0,a.mdx)("inlineCode",{parentName:"p"},"MySQLConfig"),".\nIt is actually an instance of ",(0,a.mdx)("inlineCode",{parentName:"p"},"DictConfig"),". The duck typing enables static type checking by tools like Mypy or PyCharm.\nThis reduces development time by catching coding errors before you run your application."),(0,a.mdx)("p",null,"The name ",(0,a.mdx)("a",{parentName:"p",href:"https://en.wikipedia.org/wiki/Duck_typing"},"Duck typing"),' comes from the phrase "If it walks like a duck, swims like a duck, and quacks like a duck, then it probably is a duck".\nIt can be useful when you care about the methods or attributes of an object, not the actual type of the object.'))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/315f70d7.ccb4a276.js b/assets/js/315f70d7.ccb4a276.js new file mode 100644 index 0000000000..63f190ed2d --- /dev/null +++ b/assets/js/315f70d7.ccb4a276.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[6448],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>p,MDXProvider:()=>u,mdx:()=>f,useMDXComponents:()=>s,withMDXComponents:()=>m});var r=n(96540);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var p=r.createContext({}),m=function(e){return function(t){var n=s(t.components);return r.createElement(e,a({},t,{components:n}))}},s=function(e){var t=r.useContext(p),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},u=function(e){var t=s(e.components);return r.createElement(p.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},y=r.forwardRef((function(e,t){var n=e.components,i=e.mdxType,a=e.originalType,o=e.parentName,p=c(e,["components","mdxType","originalType","parentName"]),m=s(n),u=i,y=m["".concat(o,".").concat(u)]||m[u]||d[u]||a;return n?r.createElement(y,l(l({ref:t},p),{},{components:n})):r.createElement(y,l({ref:t},p))}));function f(e,t){var n=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var a=n.length,o=new Array(a);o[0]=y;var l={};for(var c in t)hasOwnProperty.call(t,c)&&(l[c]=t[c]);l.originalType=e,l.mdxType="string"==typeof e?e:i,o[1]=l;for(var p=2;p{n.d(t,{A:()=>c,C:()=>p});var r=n(58168),i=n(96540),a=n(75489),o=n(44586),l=n(74098);function c(e){return i.createElement(a.default,(0,r.A)({},e,{to:(t=e.to,c=(0,l.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==c?void 0:c.name)?n:"current"]+t),target:"_blank"}));var t,n,c}function p(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return i.createElement(c,e,i.createElement("span",null,"\xa0"),i.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},84358:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>p,default:()=>d,frontMatter:()=>c,metadata:()=>m,toc:()=>s});var r=n(58168),i=n(98587),a=(n(96540),n(15680)),o=n(49595),l=["components"],c={id:"minimal_example",title:"Minimal example"},p=void 0,m={unversionedId:"tutorials/structured_config/minimal_example",id:"version-1.2/tutorials/structured_config/minimal_example",title:"Minimal example",description:"There are four key elements in this example:",source:"@site/versioned_docs/version-1.2/tutorials/structured_config/1_minimal_example.md",sourceDirName:"tutorials/structured_config",slug:"/tutorials/structured_config/minimal_example",permalink:"/docs/1.2/tutorials/structured_config/minimal_example",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/tutorials/structured_config/1_minimal_example.md",tags:[],version:"1.2",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:1,frontMatter:{id:"minimal_example",title:"Minimal example"},sidebar:"docs",previous:{title:"Config Store API",permalink:"/docs/1.2/tutorials/structured_config/config_store"},next:{title:"A hierarchical static configuration",permalink:"/docs/1.2/tutorials/structured_config/hierarchical_static_config"}},s=[{value:"Duck-typing enables static type checking",id:"duck-typing-enables-static-type-checking",children:[],level:3},{value:"Structured Configs enable Hydra to catch type errors at runtime",id:"structured-configs-enable-hydra-to-catch-type-errors-at-runtime",children:[],level:3},{value:"Duck typing",id:"duck-typing",children:[],level:2}],u={toc:s};function d(e){var t=e.components,n=(0,i.A)(e,l);return(0,a.mdx)("wrapper",(0,r.A)({},u,n,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)(o.C,{to:"examples/tutorials/structured_configs/1_minimal",mdxType:"ExampleGithubLink"}),(0,a.mdx)("p",null,"There are four key elements in this example:"),(0,a.mdx)("ul",null,(0,a.mdx)("li",{parentName:"ul"},"A ",(0,a.mdx)("inlineCode",{parentName:"li"},"@dataclass")," describes the application's configuration"),(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"ConfigStore")," manages the Structured Config"),(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"cfg")," is ",(0,a.mdx)("inlineCode",{parentName:"li"},"duck typed")," as a ",(0,a.mdx)("inlineCode",{parentName:"li"},"MySQLConfig")," instead of a ",(0,a.mdx)("inlineCode",{parentName:"li"},"DictConfig")),(0,a.mdx)("li",{parentName:"ul"},"There is a subtle typo in the code below, can you spot it?")),(0,a.mdx)("p",null,"In this example, the config node stored in the ",(0,a.mdx)("inlineCode",{parentName:"p"},"ConfigStore")," replaces the traditional ",(0,a.mdx)("inlineCode",{parentName:"p"},"config.yaml")," file."),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app_type_error.py" {18}',title:'"my_app_type_error.py"',"{18}":!0},'from dataclasses import dataclass\n\nimport hydra\nfrom hydra.core.config_store import ConfigStore\n\n@dataclass\nclass MySQLConfig:\n host: str = "localhost"\n port: int = 3306\n\ncs = ConfigStore.instance()\n# Registering the Config class with the name \'config\'.\ncs.store(name="config", node=MySQLConfig)\n\n@hydra.main(version_base=None, config_name="config")\ndef my_app(cfg: MySQLConfig) -> None:\n # pork should be port!\n if cfg.pork == 80:\n print("Is this a webserver?!")\n\nif __name__ == "__main__":\n my_app()\n')),(0,a.mdx)("h3",{id:"duck-typing-enables-static-type-checking"},"Duck-typing enables static type checking"),(0,a.mdx)("p",null,"Duck-typing the config object as ",(0,a.mdx)("inlineCode",{parentName:"p"},"MySQLConfig")," enables static type checkers like ",(0,a.mdx)("inlineCode",{parentName:"p"},"mypy")," to catch\ntype errors before you run your code:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="$ mypy my_app_type_error.py"',title:'"$',mypy:!0,'my_app_type_error.py"':!0},'my_app_type_error.py:22: error: "MySQLConfig" has no attribute "pork"\nFound 1 error in 1 file (checked 1 source file)\n')),(0,a.mdx)("h3",{id:"structured-configs-enable-hydra-to-catch-type-errors-at-runtime"},"Structured Configs enable Hydra to catch type errors at runtime"),(0,a.mdx)("p",null,"If you forget to run ",(0,a.mdx)("inlineCode",{parentName:"p"},"mypy"),", Hydra will report the error at runtime:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="$ python my_app_type_error.py"',title:'"$',python:!0,'my_app_type_error.py"':!0},"Traceback (most recent call last):\n File \"my_app_type_error.py\", line 22, in my_app\n if cfg.pork == 80:\nomegaconf.errors.ConfigAttributeError: Key 'pork' not in 'MySQLConfig'\n full_key: pork\n object_type=MySQLConfig\n\nSet the environment variable HYDRA_FULL_ERROR=1 for a complete stack trace.\n")),(0,a.mdx)("p",null,"Hydra will also catch typos, or type errors in the command line:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre"},"$ python my_app_type_error.py port=fail\nError merging override port=fail\nValue 'fail' could not be converted to Integer\n full_key: port\n object_type=MySQLConfig\n")),(0,a.mdx)("p",null,"We will see additional types of runtime errors that Hydra can catch later in this tutorial. Such as:"),(0,a.mdx)("ul",null,(0,a.mdx)("li",{parentName:"ul"},"Trying to read or write a non existent field in your config object"),(0,a.mdx)("li",{parentName:"ul"},"Assigning a value that is incompatible with the declared type"),(0,a.mdx)("li",{parentName:"ul"},"Attempting to modify a ",(0,a.mdx)("a",{parentName:"li",href:"https://omegaconf.readthedocs.io/en/latest/structured_config.html#frozen"},"frozen config"))),(0,a.mdx)("h2",{id:"duck-typing"},"Duck typing"),(0,a.mdx)("p",null,"In the example above ",(0,a.mdx)("inlineCode",{parentName:"p"},"cfg")," is duck typed as ",(0,a.mdx)("inlineCode",{parentName:"p"},"MySQLConfig"),".\nIt is actually an instance of ",(0,a.mdx)("inlineCode",{parentName:"p"},"DictConfig"),". The duck typing enables static type checking by tools like Mypy or PyCharm.\nThis reduces development time by catching coding errors before you run your application."),(0,a.mdx)("p",null,"The name ",(0,a.mdx)("a",{parentName:"p",href:"https://en.wikipedia.org/wiki/Duck_typing"},"Duck typing"),' comes from the phrase "If it walks like a duck, swims like a duck, and quacks like a duck, then it probably is a duck".\nIt can be useful when you care about the methods or attributes of an object, not the actual type of the object.'))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/318b0639.25d39d53.js b/assets/js/318b0639.25d39d53.js deleted file mode 100644 index 9c1023b20e..0000000000 --- a/assets/js/318b0639.25d39d53.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[1707],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>l,MDXProvider:()=>c,mdx:()=>f,useMDXComponents:()=>m,withMDXComponents:()=>s});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var l=r.createContext({}),s=function(e){return function(t){var n=m(t.components);return r.createElement(e,a({},t,{components:n}))}},m=function(e){var t=r.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):d(d({},t),e)),n},c=function(e){var t=m(e.components);return r.createElement(l.Provider,{value:t},e.children)},v={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},u=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,l=p(e,["components","mdxType","originalType","parentName"]),s=m(n),c=o,u=s["".concat(i,".").concat(c)]||s[c]||v[c]||a;return n?r.createElement(u,d(d({ref:t},l),{},{components:n})):r.createElement(u,d({ref:t},l))}));function f(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=n.length,i=new Array(a);i[0]=u;var d={};for(var p in t)hasOwnProperty.call(t,p)&&(d[p]=t[p]);d.originalType=e,d.mdxType="string"==typeof e?e:o,i[1]=d;for(var l=2;l{n.r(t),n.d(t,{contentTitle:()=>p,default:()=>c,frontMatter:()=>d,metadata:()=>l,toc:()=>s});var r=n(58168),o=n(98587),a=(n(96540),n(15680)),i=["components"],d={id:"overview",title:"Developer Guide Overview"},p=void 0,l={unversionedId:"development/overview",id:"version-1.1/development/overview",title:"Developer Guide Overview",description:"This guide assumes you have checked-out the repository.",source:"@site/versioned_docs/version-1.1/development/overview.md",sourceDirName:"development",slug:"/development/overview",permalink:"/docs/1.1/development/overview",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/development/overview.md",tags:[],version:"1.1",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"overview",title:"Developer Guide Overview"},sidebar:"version-1.1/docs",previous:{title:"Callbacks",permalink:"/docs/1.1/experimental/callbacks"},next:{title:"Testing",permalink:"/docs/1.1/development/testing"}},s=[{value:"Environment setup",id:"environment-setup",children:[],level:2}],m={toc:s};function c(e){var t=e.components,n=(0,o.A)(e,i);return(0,a.mdx)("wrapper",(0,r.A)({},m,n,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)("p",null,"This guide assumes you have checked-out the ",(0,a.mdx)("a",{parentName:"p",href:"https://github.com/facebookresearch/hydra"},"repository"),".\nIt is recommended that you install Hydra in a virtual environment like ",(0,a.mdx)("a",{parentName:"p",href:"https://docs.conda.io/en/latest/"},"conda")," or ",(0,a.mdx)("a",{parentName:"p",href:"https://virtualenv.pypa.io/en/latest/"},"virtualenv"),"."),(0,a.mdx)("h2",{id:"environment-setup"},"Environment setup"),(0,a.mdx)("p",null,"Install ",(0,a.mdx)("a",{parentName:"p",href:"https://docs.conda.io/en/latest/miniconda.html"},"Miniconda")," and create an empty Conda environment with:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre"},"conda create -n hydra38 python=3.8 -qy\n")),(0,a.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,a.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,a.mdx)("h5",{parentName:"div"},(0,a.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,a.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,a.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"NOTE")),(0,a.mdx)("div",{parentName:"div",className:"admonition-content"},(0,a.mdx)("p",{parentName:"div"},"The core Hydra framework supports Python 3.6 or newer. You may need to create additional environments for different Python versions if CI detect issues on a supported version of Python."))),(0,a.mdx)("p",null,"Activate the environment:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre"},"conda activate hydra38\n")),(0,a.mdx)("p",null,"From the source tree, install Hydra in development mode with the following commands:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-bash"},"# install development dependencies\npip install -r requirements/dev.txt\n# install Hydra in development (editable) mode\npip install -e .\n")))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/318b0639.452275ee.js b/assets/js/318b0639.452275ee.js new file mode 100644 index 0000000000..bf36a3a833 --- /dev/null +++ b/assets/js/318b0639.452275ee.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[1707],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>l,MDXProvider:()=>c,mdx:()=>f,useMDXComponents:()=>m,withMDXComponents:()=>s});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var l=r.createContext({}),s=function(e){return function(t){var n=m(t.components);return r.createElement(e,a({},t,{components:n}))}},m=function(e){var t=r.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):d(d({},t),e)),n},c=function(e){var t=m(e.components);return r.createElement(l.Provider,{value:t},e.children)},v={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},u=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,l=p(e,["components","mdxType","originalType","parentName"]),s=m(n),c=o,u=s["".concat(i,".").concat(c)]||s[c]||v[c]||a;return n?r.createElement(u,d(d({ref:t},l),{},{components:n})):r.createElement(u,d({ref:t},l))}));function f(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=n.length,i=new Array(a);i[0]=u;var d={};for(var p in t)hasOwnProperty.call(t,p)&&(d[p]=t[p]);d.originalType=e,d.mdxType="string"==typeof e?e:o,i[1]=d;for(var l=2;l{n.r(t),n.d(t,{contentTitle:()=>p,default:()=>c,frontMatter:()=>d,metadata:()=>l,toc:()=>s});var r=n(58168),o=n(98587),a=(n(96540),n(15680)),i=["components"],d={id:"overview",title:"Developer Guide Overview"},p=void 0,l={unversionedId:"development/overview",id:"version-1.1/development/overview",title:"Developer Guide Overview",description:"This guide assumes you have checked-out the repository.",source:"@site/versioned_docs/version-1.1/development/overview.md",sourceDirName:"development",slug:"/development/overview",permalink:"/docs/1.1/development/overview",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/development/overview.md",tags:[],version:"1.1",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"overview",title:"Developer Guide Overview"},sidebar:"version-1.1/docs",previous:{title:"Callbacks",permalink:"/docs/1.1/experimental/callbacks"},next:{title:"Testing",permalink:"/docs/1.1/development/testing"}},s=[{value:"Environment setup",id:"environment-setup",children:[],level:2}],m={toc:s};function c(e){var t=e.components,n=(0,o.A)(e,i);return(0,a.mdx)("wrapper",(0,r.A)({},m,n,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)("p",null,"This guide assumes you have checked-out the ",(0,a.mdx)("a",{parentName:"p",href:"https://github.com/facebookresearch/hydra"},"repository"),".\nIt is recommended that you install Hydra in a virtual environment like ",(0,a.mdx)("a",{parentName:"p",href:"https://docs.conda.io/en/latest/"},"conda")," or ",(0,a.mdx)("a",{parentName:"p",href:"https://virtualenv.pypa.io/en/latest/"},"virtualenv"),"."),(0,a.mdx)("h2",{id:"environment-setup"},"Environment setup"),(0,a.mdx)("p",null,"Install ",(0,a.mdx)("a",{parentName:"p",href:"https://docs.conda.io/en/latest/miniconda.html"},"Miniconda")," and create an empty Conda environment with:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre"},"conda create -n hydra38 python=3.8 -qy\n")),(0,a.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,a.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,a.mdx)("h5",{parentName:"div"},(0,a.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,a.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,a.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"NOTE")),(0,a.mdx)("div",{parentName:"div",className:"admonition-content"},(0,a.mdx)("p",{parentName:"div"},"The core Hydra framework supports Python 3.6 or newer. You may need to create additional environments for different Python versions if CI detect issues on a supported version of Python."))),(0,a.mdx)("p",null,"Activate the environment:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre"},"conda activate hydra38\n")),(0,a.mdx)("p",null,"From the source tree, install Hydra in development mode with the following commands:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-bash"},"# install development dependencies\npip install -r requirements/dev.txt\n# install Hydra in development (editable) mode\npip install -e .\n")))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/338ef806.626052e7.js b/assets/js/338ef806.626052e7.js new file mode 100644 index 0000000000..0847a40880 --- /dev/null +++ b/assets/js/338ef806.626052e7.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3152],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>d,MDXProvider:()=>p,mdx:()=>f,useMDXComponents:()=>c,withMDXComponents:()=>m});var r=t(96540);function a(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function o(){return o=Object.assign||function(e){for(var n=1;n=0||(a[t]=e[t]);return a}(e,n);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(a[t]=e[t])}return a}var d=r.createContext({}),m=function(e){return function(n){var t=c(n.components);return r.createElement(e,o({},n,{components:t}))}},c=function(e){var n=r.useContext(d),t=n;return e&&(t="function"==typeof e?e(n):s(s({},n),e)),t},p=function(e){var n=c(e.components);return r.createElement(d.Provider,{value:n},e.children)},g={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},u=r.forwardRef((function(e,n){var t=e.components,a=e.mdxType,o=e.originalType,i=e.parentName,d=l(e,["components","mdxType","originalType","parentName"]),m=c(t),p=a,u=m["".concat(i,".").concat(p)]||m[p]||g[p]||o;return t?r.createElement(u,s(s({ref:n},d),{},{components:t})):r.createElement(u,s({ref:n},d))}));function f(e,n){var t=arguments,a=n&&n.mdxType;if("string"==typeof e||a){var o=t.length,i=new Array(o);i[0]=u;var s={};for(var l in n)hasOwnProperty.call(n,l)&&(s[l]=n[l]);s.originalType=e,s.mdxType="string"==typeof e?e:a,i[1]=s;for(var d=2;d{t.d(n,{A:()=>l,C:()=>d});var r=t(58168),a=t(96540),o=t(75489),i=t(44586),s=t(74098);function l(e){return a.createElement(o.default,(0,r.A)({},e,{to:(n=e.to,l=(0,s.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==l?void 0:l.name)?t:"current"]+n),target:"_blank"}));var n,t,l}function d(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return a.createElement(l,e,a.createElement("span",null,"\xa0"),a.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},79636:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>d,default:()=>g,frontMatter:()=>l,metadata:()=>m,toc:()=>c});var r=t(58168),a=t(98587),o=(t(96540),t(15680)),i=t(49595),s=["components"],l={id:"extending_configs",title:"Extending Configs"},d=void 0,m={unversionedId:"patterns/extending_configs",id:"version-1.3/patterns/extending_configs",title:"Extending Configs",description:"A common pattern is to extend an existing config, overriding and/or adding new config values to it.",source:"@site/versioned_docs/version-1.3/patterns/extending_configs.md",sourceDirName:"patterns",slug:"/patterns/extending_configs",permalink:"/docs/1.3/patterns/extending_configs",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/patterns/extending_configs.md",tags:[],version:"1.3",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"extending_configs",title:"Extending Configs"},sidebar:"docs",previous:{title:"Structured Config schema",permalink:"/docs/1.3/tutorials/structured_config/schema"},next:{title:"Configuring Experiments",permalink:"/docs/1.3/patterns/configuring_experiments"}},c=[{value:"Extending a config from the same config group:",id:"extending-a-config-from-the-same-config-group",children:[],level:4},{value:"Extending a config from another config group:",id:"extending-a-config-from-another-config-group",children:[],level:4}],p={toc:c};function g(e){var n=e.components,t=(0,a.A)(e,s);return(0,o.mdx)("wrapper",(0,r.A)({},p,t,{components:n,mdxType:"MDXLayout"}),(0,o.mdx)(i.C,{text:"Example application",to:"examples/patterns/extending_configs",mdxType:"ExampleGithubLink"}),(0,o.mdx)("p",null,"A common pattern is to extend an existing config, overriding and/or adding new config values to it.\nThe extension is done by including the base configuration, and then overriding the chosen values in the current config."),(0,o.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,o.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,o.mdx)("h5",{parentName:"div"},(0,o.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,o.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,o.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"info")),(0,o.mdx)("div",{parentName:"div",className:"admonition-content"},(0,o.mdx)("p",{parentName:"div"},"This page assumes that you are familiar with the contents of ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.3/advanced/defaults_list"},"The Defaults List"),"."))),(0,o.mdx)("h4",{id:"extending-a-config-from-the-same-config-group"},"Extending a config from the same config group:"),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--4"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - db: mysql \n\n\n\n\n\n"))),(0,o.mdx)("div",{className:"col col--4"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml" {2}',title:'"db/mysql.yaml"',"{2}":!0},"defaults:\n - base_mysql\n\nuser: omry\npassword: secret\nport: 3307\nencoding: utf8\n"))),(0,o.mdx)("div",{className:"col col--4"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/base_mysql.yaml"',title:'"db/base_mysql.yaml"'},"host: localhost\nport: 3306\nuser: ???\npassword: ???\n\n\n\n")))),(0,o.mdx)("p",null,"Output:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py"',title:'"$',python:!0,'my_app.py"':!0},"db:\n host: localhost # from db/base_mysql\n port: 3307 # overridden by db/mysql.yaml \n user: omry # populated by db/mysql.yaml\n password: secret # populated by db/mysql.yaml\n encoding: utf8 # added by db/mysql.yaml\n")),(0,o.mdx)("h4",{id:"extending-a-config-from-another-config-group"},"Extending a config from another config group:"),(0,o.mdx)("p",null,"To extend a config from a different config group, include it using an absolute path (/), and override\nthe package to ",(0,o.mdx)("em",{parentName:"p"},"_","here","_"),". (",(0,o.mdx)("em",{parentName:"p"},"_","here","_")," is described in ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.3/advanced/overriding_packages#default-list-package-keywords"},"Packages"),")"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml" {2}',title:'"db/mysql.yaml"',"{2}":!0},"defaults:\n - /db_schema/base_mysql@_here_\n")),(0,o.mdx)("p",null,"It is otherwise identical to extending a config within the same config group."))}g.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/338ef806.f305e0fe.js b/assets/js/338ef806.f305e0fe.js deleted file mode 100644 index f2227be4fa..0000000000 --- a/assets/js/338ef806.f305e0fe.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3152],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>d,MDXProvider:()=>p,mdx:()=>f,useMDXComponents:()=>c,withMDXComponents:()=>m});var r=t(96540);function a(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function o(){return o=Object.assign||function(e){for(var n=1;n=0||(a[t]=e[t]);return a}(e,n);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(a[t]=e[t])}return a}var d=r.createContext({}),m=function(e){return function(n){var t=c(n.components);return r.createElement(e,o({},n,{components:t}))}},c=function(e){var n=r.useContext(d),t=n;return e&&(t="function"==typeof e?e(n):s(s({},n),e)),t},p=function(e){var n=c(e.components);return r.createElement(d.Provider,{value:n},e.children)},g={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},u=r.forwardRef((function(e,n){var t=e.components,a=e.mdxType,o=e.originalType,i=e.parentName,d=l(e,["components","mdxType","originalType","parentName"]),m=c(t),p=a,u=m["".concat(i,".").concat(p)]||m[p]||g[p]||o;return t?r.createElement(u,s(s({ref:n},d),{},{components:t})):r.createElement(u,s({ref:n},d))}));function f(e,n){var t=arguments,a=n&&n.mdxType;if("string"==typeof e||a){var o=t.length,i=new Array(o);i[0]=u;var s={};for(var l in n)hasOwnProperty.call(n,l)&&(s[l]=n[l]);s.originalType=e,s.mdxType="string"==typeof e?e:a,i[1]=s;for(var d=2;d{t.d(n,{A:()=>l,C:()=>d});var r=t(58168),a=t(96540),o=t(75489),i=t(44586),s=t(74098);function l(e){return a.createElement(o.default,(0,r.A)({},e,{to:(n=e.to,l=(0,s.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==l?void 0:l.name)?t:"current"]+n),target:"_blank"}));var n,t,l}function d(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return a.createElement(l,e,a.createElement("span",null,"\xa0"),a.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},79636:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>d,default:()=>g,frontMatter:()=>l,metadata:()=>m,toc:()=>c});var r=t(58168),a=t(98587),o=(t(96540),t(15680)),i=t(49595),s=["components"],l={id:"extending_configs",title:"Extending Configs"},d=void 0,m={unversionedId:"patterns/extending_configs",id:"version-1.3/patterns/extending_configs",title:"Extending Configs",description:"A common pattern is to extend an existing config, overriding and/or adding new config values to it.",source:"@site/versioned_docs/version-1.3/patterns/extending_configs.md",sourceDirName:"patterns",slug:"/patterns/extending_configs",permalink:"/docs/1.3/patterns/extending_configs",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/patterns/extending_configs.md",tags:[],version:"1.3",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"extending_configs",title:"Extending Configs"},sidebar:"docs",previous:{title:"Structured Config schema",permalink:"/docs/1.3/tutorials/structured_config/schema"},next:{title:"Configuring Experiments",permalink:"/docs/1.3/patterns/configuring_experiments"}},c=[{value:"Extending a config from the same config group:",id:"extending-a-config-from-the-same-config-group",children:[],level:4},{value:"Extending a config from another config group:",id:"extending-a-config-from-another-config-group",children:[],level:4}],p={toc:c};function g(e){var n=e.components,t=(0,a.A)(e,s);return(0,o.mdx)("wrapper",(0,r.A)({},p,t,{components:n,mdxType:"MDXLayout"}),(0,o.mdx)(i.C,{text:"Example application",to:"examples/patterns/extending_configs",mdxType:"ExampleGithubLink"}),(0,o.mdx)("p",null,"A common pattern is to extend an existing config, overriding and/or adding new config values to it.\nThe extension is done by including the base configuration, and then overriding the chosen values in the current config."),(0,o.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,o.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,o.mdx)("h5",{parentName:"div"},(0,o.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,o.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,o.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"info")),(0,o.mdx)("div",{parentName:"div",className:"admonition-content"},(0,o.mdx)("p",{parentName:"div"},"This page assumes that you are familiar with the contents of ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.3/advanced/defaults_list"},"The Defaults List"),"."))),(0,o.mdx)("h4",{id:"extending-a-config-from-the-same-config-group"},"Extending a config from the same config group:"),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--4"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - db: mysql \n\n\n\n\n\n"))),(0,o.mdx)("div",{className:"col col--4"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml" {2}',title:'"db/mysql.yaml"',"{2}":!0},"defaults:\n - base_mysql\n\nuser: omry\npassword: secret\nport: 3307\nencoding: utf8\n"))),(0,o.mdx)("div",{className:"col col--4"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/base_mysql.yaml"',title:'"db/base_mysql.yaml"'},"host: localhost\nport: 3306\nuser: ???\npassword: ???\n\n\n\n")))),(0,o.mdx)("p",null,"Output:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py"',title:'"$',python:!0,'my_app.py"':!0},"db:\n host: localhost # from db/base_mysql\n port: 3307 # overridden by db/mysql.yaml \n user: omry # populated by db/mysql.yaml\n password: secret # populated by db/mysql.yaml\n encoding: utf8 # added by db/mysql.yaml\n")),(0,o.mdx)("h4",{id:"extending-a-config-from-another-config-group"},"Extending a config from another config group:"),(0,o.mdx)("p",null,"To extend a config from a different config group, include it using an absolute path (/), and override\nthe package to ",(0,o.mdx)("em",{parentName:"p"},"_","here","_"),". (",(0,o.mdx)("em",{parentName:"p"},"_","here","_")," is described in ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.3/advanced/overriding_packages#default-list-package-keywords"},"Packages"),")"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml" {2}',title:'"db/mysql.yaml"',"{2}":!0},"defaults:\n - /db_schema/base_mysql@_here_\n")),(0,o.mdx)("p",null,"It is otherwise identical to extending a config within the same config group."))}g.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/33afe7db.667437f6.js b/assets/js/33afe7db.667437f6.js deleted file mode 100644 index c46c9cbbd9..0000000000 --- a/assets/js/33afe7db.667437f6.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[8678],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>m,MDXProvider:()=>d,mdx:()=>f,useMDXComponents:()=>p,withMDXComponents:()=>c});var a=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function r(){return r=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var m=a.createContext({}),c=function(e){return function(t){var n=p(t.components);return a.createElement(e,r({},t,{components:n}))}},p=function(e){var t=a.useContext(m),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},d=function(e){var t=p(e.components);return a.createElement(m.Provider,{value:t},e.children)},g={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},u=a.forwardRef((function(e,t){var n=e.components,o=e.mdxType,r=e.originalType,l=e.parentName,m=s(e,["components","mdxType","originalType","parentName"]),c=p(n),d=o,u=c["".concat(l,".").concat(d)]||c[d]||g[d]||r;return n?a.createElement(u,i(i({ref:t},m),{},{components:n})):a.createElement(u,i({ref:t},m))}));function f(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var r=n.length,l=new Array(r);l[0]=u;var i={};for(var s in t)hasOwnProperty.call(t,s)&&(i[s]=t[s]);i.originalType=e,i.mdxType="string"==typeof e?e:o,l[1]=i;for(var m=2;m{n.d(t,{A:()=>s,C:()=>m});var a=n(58168),o=n(96540),r=n(75489),l=n(44586),i=n(74098);function s(e){return o.createElement(r.default,(0,a.A)({},e,{to:(t=e.to,s=(0,i.useActiveVersion)(),(0,l.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==s?void 0:s.name)?n:"current"]+t),target:"_blank"}));var t,n,s}function m(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return o.createElement(s,e,o.createElement("span",null,"\xa0"),o.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},88123:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>m,default:()=>g,frontMatter:()=>s,metadata:()=>c,toc:()=>p});var a=n(58168),o=n(98587),r=(n(96540),n(15680)),l=n(49595),i=["components"],s={id:"select_multiple_configs_from_config_group",title:"Selecting multiple configs from a Config Group"},m=void 0,c={unversionedId:"patterns/select_multiple_configs_from_config_group",id:"version-1.1/patterns/select_multiple_configs_from_config_group",title:"Selecting multiple configs from a Config Group",description:"Problem",source:"@site/versioned_docs/version-1.1/patterns/select_multiple_configs_from_config_group.md",sourceDirName:"patterns",slug:"/patterns/select_multiple_configs_from_config_group",permalink:"/docs/1.1/patterns/select_multiple_configs_from_config_group",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/patterns/select_multiple_configs_from_config_group.md",tags:[],version:"1.1",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"select_multiple_configs_from_config_group",title:"Selecting multiple configs from a Config Group"},sidebar:"version-1.1/docs",previous:{title:"Configuring Plugins",permalink:"/docs/1.1/patterns/configuring_plugins"},next:{title:"Specializing configuration",permalink:"/docs/1.1/patterns/specializing_config"}},p=[{value:"Problem",id:"problem",children:[],level:3},{value:"Solution",id:"solution",children:[],level:3},{value:"Example",id:"example",children:[],level:3},{value:"Overriding packages",id:"overriding-packages",children:[],level:3},{value:"Implementation considerations",id:"implementation-considerations",children:[],level:3}],d={toc:p};function g(e){var t=e.components,n=(0,o.A)(e,i);return(0,r.mdx)("wrapper",(0,a.A)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,r.mdx)(l.C,{text:"Example application",to:"examples/patterns/multi-select",mdxType:"ExampleGithubLink"}),(0,r.mdx)("h3",{id:"problem"},"Problem"),(0,r.mdx)("p",null,"In some scenarios, one may need to select multiple configs from the same Config Group."),(0,r.mdx)("h3",{id:"solution"},"Solution"),(0,r.mdx)("p",null,"Use a list of config names as the value of the config group in the Defaults List or in the command line."),(0,r.mdx)("h3",{id:"example"},"Example"),(0,r.mdx)("p",null,"In this example, we configure a server. The server can host multiple websites at the same time."),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Config directory"',title:'"Config','directory"':!0},"\u251c\u2500\u2500 config.yaml\n\u2514\u2500\u2500 server\n \u251c\u2500\u2500 apache.yaml\n \u2514\u2500\u2500 site\n \u251c\u2500\u2500 amazon.yaml\n \u251c\u2500\u2500 fb.yaml\n \u2514\u2500\u2500 google.yaml\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - server/apache\n\n\n\n\n\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/apache.yaml" {3,4}',title:'"server/apache.yaml"',"{3,4}":!0},"defaults:\n - site:\n - fb\n - google\n\nhost: localhost\nport: 443\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/site/amazon.yaml"',title:'"server/site/amazon.yaml"'},"amazon:\n domain: amazon.com\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/site/fb.yaml"',title:'"server/site/fb.yaml"'},"fb:\n domain: facebook.com\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/site/google.yaml"',title:'"server/site/google.yaml"'},"google:\n domain: google.com\n")))),(0,r.mdx)("p",null,"Output:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py" {3,5}',title:'"$',python:!0,'my_app.py"':!0,"{3,5}":!0},"server:\n site:\n fb:\n domain: facebook.com\n google:\n domain: google.com\n host: localhost\n port: 443\n")),(0,r.mdx)("p",null,"Override the selected sites from the command line by passing a list. e.g:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"title=\"$ python my_app.py 'server/site=[google,amazon]'\" {3,5}",title:'"$',python:!0,"my_app.py":!0,"'server/site":"[google,amazon]'\"","{3,5}":!0},"server:\n site:\n google:\n domain: google.com\n amazon:\n domain: amazon.com\n host: localhost\n port: 443\n")),(0,r.mdx)("h3",{id:"overriding-packages"},"Overriding packages"),(0,r.mdx)("p",null,"You can relocate the package of all the configs in the list. e.g:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/apache.yaml" {2}',title:'"server/apache.yaml"',"{2}":!0},"defaults:\n - site@https:\n - fb\n - google\n\n\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py" {2}',title:'"$',python:!0,'my_app.py"':!0,"{2}":!0},"server:\n https:\n fb:\n domain: facebook.com\n google:\n domain: google.com\n")))),(0,r.mdx)("p",null,"When overriding the selected configs of config groups with overridden packages you need to use the package. e.g:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py server/site@server.https=amazon"',title:'"$',python:!0,"my_app.py":!0,"server/site@server.https":'amazon"'},"server:\n https:\n amazon:\n domain: amazon.com\n host: localhost\n port: 443\n")),(0,r.mdx)("h3",{id:"implementation-considerations"},"Implementation considerations"),(0,r.mdx)("p",null,"A nested list in the Defaults List is interpreted as a list of non-overridable configs:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/apache.yaml" {3,4}',title:'"server/apache.yaml"',"{3,4}":!0},"defaults:\n - site:\n - fb\n - google\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Equivalent to" {2,3}',title:'"Equivalent','to"':!0,"{2,3}":!0},"defaults:\n - site/fb\n - site/google\n\n")))),(0,r.mdx)("p",null,"All default package for all the configs in ",(0,r.mdx)("inlineCode",{parentName:"p"},"server/site")," is ",(0,r.mdx)("inlineCode",{parentName:"p"},"server.site"),".\nThis example uses an explicit nesting level inside each of the website configs to prevent them stepping over one another:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/site/amazon.yaml" {1}',title:'"server/site/amazon.yaml"',"{1}":!0},"amazon:\n ...\n")))}g.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/33afe7db.8bf5b107.js b/assets/js/33afe7db.8bf5b107.js new file mode 100644 index 0000000000..cf27ad0855 --- /dev/null +++ b/assets/js/33afe7db.8bf5b107.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[8678],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>m,MDXProvider:()=>d,mdx:()=>f,useMDXComponents:()=>p,withMDXComponents:()=>c});var a=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function r(){return r=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var m=a.createContext({}),c=function(e){return function(t){var n=p(t.components);return a.createElement(e,r({},t,{components:n}))}},p=function(e){var t=a.useContext(m),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},d=function(e){var t=p(e.components);return a.createElement(m.Provider,{value:t},e.children)},g={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},u=a.forwardRef((function(e,t){var n=e.components,o=e.mdxType,r=e.originalType,l=e.parentName,m=s(e,["components","mdxType","originalType","parentName"]),c=p(n),d=o,u=c["".concat(l,".").concat(d)]||c[d]||g[d]||r;return n?a.createElement(u,i(i({ref:t},m),{},{components:n})):a.createElement(u,i({ref:t},m))}));function f(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var r=n.length,l=new Array(r);l[0]=u;var i={};for(var s in t)hasOwnProperty.call(t,s)&&(i[s]=t[s]);i.originalType=e,i.mdxType="string"==typeof e?e:o,l[1]=i;for(var m=2;m{n.d(t,{A:()=>s,C:()=>m});var a=n(58168),o=n(96540),r=n(75489),l=n(44586),i=n(74098);function s(e){return o.createElement(r.default,(0,a.A)({},e,{to:(t=e.to,s=(0,i.useActiveVersion)(),(0,l.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==s?void 0:s.name)?n:"current"]+t),target:"_blank"}));var t,n,s}function m(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return o.createElement(s,e,o.createElement("span",null,"\xa0"),o.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},88123:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>m,default:()=>g,frontMatter:()=>s,metadata:()=>c,toc:()=>p});var a=n(58168),o=n(98587),r=(n(96540),n(15680)),l=n(49595),i=["components"],s={id:"select_multiple_configs_from_config_group",title:"Selecting multiple configs from a Config Group"},m=void 0,c={unversionedId:"patterns/select_multiple_configs_from_config_group",id:"version-1.1/patterns/select_multiple_configs_from_config_group",title:"Selecting multiple configs from a Config Group",description:"Problem",source:"@site/versioned_docs/version-1.1/patterns/select_multiple_configs_from_config_group.md",sourceDirName:"patterns",slug:"/patterns/select_multiple_configs_from_config_group",permalink:"/docs/1.1/patterns/select_multiple_configs_from_config_group",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/patterns/select_multiple_configs_from_config_group.md",tags:[],version:"1.1",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"select_multiple_configs_from_config_group",title:"Selecting multiple configs from a Config Group"},sidebar:"version-1.1/docs",previous:{title:"Configuring Plugins",permalink:"/docs/1.1/patterns/configuring_plugins"},next:{title:"Specializing configuration",permalink:"/docs/1.1/patterns/specializing_config"}},p=[{value:"Problem",id:"problem",children:[],level:3},{value:"Solution",id:"solution",children:[],level:3},{value:"Example",id:"example",children:[],level:3},{value:"Overriding packages",id:"overriding-packages",children:[],level:3},{value:"Implementation considerations",id:"implementation-considerations",children:[],level:3}],d={toc:p};function g(e){var t=e.components,n=(0,o.A)(e,i);return(0,r.mdx)("wrapper",(0,a.A)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,r.mdx)(l.C,{text:"Example application",to:"examples/patterns/multi-select",mdxType:"ExampleGithubLink"}),(0,r.mdx)("h3",{id:"problem"},"Problem"),(0,r.mdx)("p",null,"In some scenarios, one may need to select multiple configs from the same Config Group."),(0,r.mdx)("h3",{id:"solution"},"Solution"),(0,r.mdx)("p",null,"Use a list of config names as the value of the config group in the Defaults List or in the command line."),(0,r.mdx)("h3",{id:"example"},"Example"),(0,r.mdx)("p",null,"In this example, we configure a server. The server can host multiple websites at the same time."),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Config directory"',title:'"Config','directory"':!0},"\u251c\u2500\u2500 config.yaml\n\u2514\u2500\u2500 server\n \u251c\u2500\u2500 apache.yaml\n \u2514\u2500\u2500 site\n \u251c\u2500\u2500 amazon.yaml\n \u251c\u2500\u2500 fb.yaml\n \u2514\u2500\u2500 google.yaml\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - server/apache\n\n\n\n\n\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/apache.yaml" {3,4}',title:'"server/apache.yaml"',"{3,4}":!0},"defaults:\n - site:\n - fb\n - google\n\nhost: localhost\nport: 443\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/site/amazon.yaml"',title:'"server/site/amazon.yaml"'},"amazon:\n domain: amazon.com\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/site/fb.yaml"',title:'"server/site/fb.yaml"'},"fb:\n domain: facebook.com\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/site/google.yaml"',title:'"server/site/google.yaml"'},"google:\n domain: google.com\n")))),(0,r.mdx)("p",null,"Output:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py" {3,5}',title:'"$',python:!0,'my_app.py"':!0,"{3,5}":!0},"server:\n site:\n fb:\n domain: facebook.com\n google:\n domain: google.com\n host: localhost\n port: 443\n")),(0,r.mdx)("p",null,"Override the selected sites from the command line by passing a list. e.g:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"title=\"$ python my_app.py 'server/site=[google,amazon]'\" {3,5}",title:'"$',python:!0,"my_app.py":!0,"'server/site":"[google,amazon]'\"","{3,5}":!0},"server:\n site:\n google:\n domain: google.com\n amazon:\n domain: amazon.com\n host: localhost\n port: 443\n")),(0,r.mdx)("h3",{id:"overriding-packages"},"Overriding packages"),(0,r.mdx)("p",null,"You can relocate the package of all the configs in the list. e.g:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/apache.yaml" {2}',title:'"server/apache.yaml"',"{2}":!0},"defaults:\n - site@https:\n - fb\n - google\n\n\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py" {2}',title:'"$',python:!0,'my_app.py"':!0,"{2}":!0},"server:\n https:\n fb:\n domain: facebook.com\n google:\n domain: google.com\n")))),(0,r.mdx)("p",null,"When overriding the selected configs of config groups with overridden packages you need to use the package. e.g:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py server/site@server.https=amazon"',title:'"$',python:!0,"my_app.py":!0,"server/site@server.https":'amazon"'},"server:\n https:\n amazon:\n domain: amazon.com\n host: localhost\n port: 443\n")),(0,r.mdx)("h3",{id:"implementation-considerations"},"Implementation considerations"),(0,r.mdx)("p",null,"A nested list in the Defaults List is interpreted as a list of non-overridable configs:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/apache.yaml" {3,4}',title:'"server/apache.yaml"',"{3,4}":!0},"defaults:\n - site:\n - fb\n - google\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Equivalent to" {2,3}',title:'"Equivalent','to"':!0,"{2,3}":!0},"defaults:\n - site/fb\n - site/google\n\n")))),(0,r.mdx)("p",null,"All default package for all the configs in ",(0,r.mdx)("inlineCode",{parentName:"p"},"server/site")," is ",(0,r.mdx)("inlineCode",{parentName:"p"},"server.site"),".\nThis example uses an explicit nesting level inside each of the website configs to prevent them stepping over one another:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/site/amazon.yaml" {1}',title:'"server/site/amazon.yaml"',"{1}":!0},"amazon:\n ...\n")))}g.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/3462c84f.2027e820.js b/assets/js/3462c84f.2027e820.js deleted file mode 100644 index 002063425d..0000000000 --- a/assets/js/3462c84f.2027e820.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[7305],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>l,MDXProvider:()=>d,mdx:()=>f,useMDXComponents:()=>m,withMDXComponents:()=>c});var r=t(96540);function o(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function a(){return a=Object.assign||function(e){for(var n=1;n=0||(o[t]=e[t]);return o}(e,n);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(o[t]=e[t])}return o}var l=r.createContext({}),c=function(e){return function(n){var t=m(n.components);return r.createElement(e,a({},n,{components:t}))}},m=function(e){var n=r.useContext(l),t=n;return e&&(t="function"==typeof e?e(n):p(p({},n),e)),t},d=function(e){var n=m(e.components);return r.createElement(l.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},g=r.forwardRef((function(e,n){var t=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,l=s(e,["components","mdxType","originalType","parentName"]),c=m(t),d=o,g=c["".concat(i,".").concat(d)]||c[d]||u[d]||a;return t?r.createElement(g,p(p({ref:n},l),{},{components:t})):r.createElement(g,p({ref:n},l))}));function f(e,n){var t=arguments,o=n&&n.mdxType;if("string"==typeof e||o){var a=t.length,i=new Array(a);i[0]=g;var p={};for(var s in n)hasOwnProperty.call(n,s)&&(p[s]=n[s]);p.originalType=e,p.mdxType="string"==typeof e?e:o,i[1]=p;for(var l=2;l{t.d(n,{A:()=>s,C:()=>l});var r=t(58168),o=t(96540),a=t(75489),i=t(44586),p=t(74098);function s(e){return o.createElement(a.default,(0,r.A)({},e,{to:(n=e.to,s=(0,p.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==s?void 0:s.name)?t:"current"]+n),target:"_blank"}));var n,t,s}function l(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return o.createElement(s,e,o.createElement("span",null,"\xa0"),o.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},85940:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>l,default:()=>u,frontMatter:()=>s,metadata:()=>c,toc:()=>m});var r=t(58168),o=t(98587),a=(t(96540),t(15680)),i=t(49595),p=["components"],s={id:"config_groups",title:"Grouping config files"},l=void 0,c={unversionedId:"tutorials/basic/your_first_app/config_groups",id:"version-1.1/tutorials/basic/your_first_app/config_groups",title:"Grouping config files",description:"Suppose you want to benchmark your application on each of PostgreSQL and MySQL. To do this, use config groups.",source:"@site/versioned_docs/version-1.1/tutorials/basic/your_first_app/4_config_groups.md",sourceDirName:"tutorials/basic/your_first_app",slug:"/tutorials/basic/your_first_app/config_groups",permalink:"/docs/1.1/tutorials/basic/your_first_app/config_groups",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/tutorials/basic/your_first_app/4_config_groups.md",tags:[],version:"1.1",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:4,frontMatter:{id:"config_groups",title:"Grouping config files"},sidebar:"version-1.1/docs",previous:{title:"Using the config object",permalink:"/docs/1.1/tutorials/basic/your_first_app/using_config"},next:{title:"Selecting default configs",permalink:"/docs/1.1/tutorials/basic/your_first_app/defaults"}},m=[{value:"Creating config groups",id:"creating-config-groups",children:[],level:3},{value:"Using config groups",id:"using-config-groups",children:[],level:3},{value:"Advanced topics",id:"advanced-topics",children:[],level:3}],d={toc:m};function u(e){var n=e.components,t=(0,o.A)(e,p);return(0,a.mdx)("wrapper",(0,r.A)({},d,t,{components:n,mdxType:"MDXLayout"}),(0,a.mdx)(i.C,{to:"examples/tutorials/basic/your_first_hydra_app/4_config_groups",mdxType:"ExampleGithubLink"}),(0,a.mdx)("p",null,"Suppose you want to benchmark your application on each of PostgreSQL and MySQL. To do this, use config groups. "),(0,a.mdx)("p",null,"A ",(0,a.mdx)("em",{parentName:"p"},(0,a.mdx)("strong",{parentName:"em"},"Config Group"))," is a named group with a set of valid options.\nSelecting a non-existent config option generates an error message with the valid options."),(0,a.mdx)("h3",{id:"creating-config-groups"},"Creating config groups"),(0,a.mdx)("p",null,"To create a config group, create a directory, e.g. ",(0,a.mdx)("inlineCode",{parentName:"p"},"db"),", to hold a file for each database configuration option.\nSince we are expecting to have multiple config groups, we will proactively move all the configuration files\ninto a ",(0,a.mdx)("inlineCode",{parentName:"p"},"conf")," directory."),(0,a.mdx)("div",{className:"row"},(0,a.mdx)("div",{className:"col col--4"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Directory layout"',title:'"Directory','layout"':!0},"\u251c\u2500 conf\n\u2502 \u2514\u2500 db\n\u2502 \u251c\u2500 mysql.yaml\n\u2502 \u2514\u2500 postgresql.yaml\n\u2514\u2500\u2500 my_app.py\n"))),(0,a.mdx)("div",{className:"col col--4"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml"',title:'"db/mysql.yaml"'},"driver: mysql\nuser: omry\npassword: secret\n\n\n"))),(0,a.mdx)("div",{className:"col col--4"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/postgresql.yaml"',title:'"db/postgresql.yaml"'},"driver: postgresql\nuser: postgres_user\npassword: drowssap\ntimeout: 10\n\n")))),(0,a.mdx)("h3",{id:"using-config-groups"},"Using config groups"),(0,a.mdx)("p",null,"Since we moved all the configs into the ",(0,a.mdx)("inlineCode",{parentName:"p"},"conf")," directory, we need to tell Hydra where to find them using the ",(0,a.mdx)("inlineCode",{parentName:"p"},"config_path")," parameter.\n",(0,a.mdx)("strong",{parentName:"p"},(0,a.mdx)("inlineCode",{parentName:"strong"},"config_path")," is a directory relative to ",(0,a.mdx)("inlineCode",{parentName:"strong"},"my_app.py")),"."),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app.py" {4}',title:'"my_app.py"',"{4}":!0},'from omegaconf import DictConfig, OmegaConf\nimport hydra\n\n@hydra.main(config_path="conf")\ndef my_app(cfg: DictConfig) -> None:\n print(OmegaConf.to_yaml(cfg))\n\nif __name__ == "__main__":\n my_app()\n')),(0,a.mdx)("p",null,"Running ",(0,a.mdx)("inlineCode",{parentName:"p"},"my_app.py")," without requesting a configuration will print an empty config."),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py\n{}\n")),(0,a.mdx)("p",null,"Select an item from a config group with ",(0,a.mdx)("inlineCode",{parentName:"p"},"+GROUP=OPTION"),", e.g: "),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{2}","{2}":!0},"$ python my_app.py +db=postgresql\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 10\n user: postgres_user\n")),(0,a.mdx)("p",null,"By default, the config group determines where the config content is placed inside the final config object.\nIn Hydra, the path to the config content is referred to as the config ",(0,a.mdx)("inlineCode",{parentName:"p"},"package"),".\nThe package of ",(0,a.mdx)("inlineCode",{parentName:"p"},"db/postgresql.yaml")," is ",(0,a.mdx)("inlineCode",{parentName:"p"},"db"),":"),(0,a.mdx)("p",null,"Like before, you can still override individual values in the resulting config:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py +db=postgresql db.timeout=20\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 20\n user: postgres_user\n")),(0,a.mdx)("h3",{id:"advanced-topics"},"Advanced topics"),(0,a.mdx)("ul",null,(0,a.mdx)("li",{parentName:"ul"},"Config content can be relocated via package overrides. See ",(0,a.mdx)("a",{parentName:"li",href:"/docs/1.1/advanced/overriding_packages"},"Reference Manual/Packages"),". "),(0,a.mdx)("li",{parentName:"ul"},"Multiple options can be selected from the same Config Group by specifying them as a list.",(0,a.mdx)("br",{parentName:"li"}),"See ",(0,a.mdx)("a",{parentName:"li",href:"/docs/1.1/patterns/select_multiple_configs_from_config_group"},"Common Patterns/Selecting multiple configs from a Config Group"))))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/3462c84f.ca121fdf.js b/assets/js/3462c84f.ca121fdf.js new file mode 100644 index 0000000000..4bc07af5a2 --- /dev/null +++ b/assets/js/3462c84f.ca121fdf.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[7305],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>l,MDXProvider:()=>d,mdx:()=>f,useMDXComponents:()=>m,withMDXComponents:()=>c});var r=t(96540);function o(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function a(){return a=Object.assign||function(e){for(var n=1;n=0||(o[t]=e[t]);return o}(e,n);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(o[t]=e[t])}return o}var l=r.createContext({}),c=function(e){return function(n){var t=m(n.components);return r.createElement(e,a({},n,{components:t}))}},m=function(e){var n=r.useContext(l),t=n;return e&&(t="function"==typeof e?e(n):p(p({},n),e)),t},d=function(e){var n=m(e.components);return r.createElement(l.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},g=r.forwardRef((function(e,n){var t=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,l=s(e,["components","mdxType","originalType","parentName"]),c=m(t),d=o,g=c["".concat(i,".").concat(d)]||c[d]||u[d]||a;return t?r.createElement(g,p(p({ref:n},l),{},{components:t})):r.createElement(g,p({ref:n},l))}));function f(e,n){var t=arguments,o=n&&n.mdxType;if("string"==typeof e||o){var a=t.length,i=new Array(a);i[0]=g;var p={};for(var s in n)hasOwnProperty.call(n,s)&&(p[s]=n[s]);p.originalType=e,p.mdxType="string"==typeof e?e:o,i[1]=p;for(var l=2;l{t.d(n,{A:()=>s,C:()=>l});var r=t(58168),o=t(96540),a=t(75489),i=t(44586),p=t(74098);function s(e){return o.createElement(a.default,(0,r.A)({},e,{to:(n=e.to,s=(0,p.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==s?void 0:s.name)?t:"current"]+n),target:"_blank"}));var n,t,s}function l(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return o.createElement(s,e,o.createElement("span",null,"\xa0"),o.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},85940:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>l,default:()=>u,frontMatter:()=>s,metadata:()=>c,toc:()=>m});var r=t(58168),o=t(98587),a=(t(96540),t(15680)),i=t(49595),p=["components"],s={id:"config_groups",title:"Grouping config files"},l=void 0,c={unversionedId:"tutorials/basic/your_first_app/config_groups",id:"version-1.1/tutorials/basic/your_first_app/config_groups",title:"Grouping config files",description:"Suppose you want to benchmark your application on each of PostgreSQL and MySQL. To do this, use config groups.",source:"@site/versioned_docs/version-1.1/tutorials/basic/your_first_app/4_config_groups.md",sourceDirName:"tutorials/basic/your_first_app",slug:"/tutorials/basic/your_first_app/config_groups",permalink:"/docs/1.1/tutorials/basic/your_first_app/config_groups",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/tutorials/basic/your_first_app/4_config_groups.md",tags:[],version:"1.1",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:4,frontMatter:{id:"config_groups",title:"Grouping config files"},sidebar:"version-1.1/docs",previous:{title:"Using the config object",permalink:"/docs/1.1/tutorials/basic/your_first_app/using_config"},next:{title:"Selecting default configs",permalink:"/docs/1.1/tutorials/basic/your_first_app/defaults"}},m=[{value:"Creating config groups",id:"creating-config-groups",children:[],level:3},{value:"Using config groups",id:"using-config-groups",children:[],level:3},{value:"Advanced topics",id:"advanced-topics",children:[],level:3}],d={toc:m};function u(e){var n=e.components,t=(0,o.A)(e,p);return(0,a.mdx)("wrapper",(0,r.A)({},d,t,{components:n,mdxType:"MDXLayout"}),(0,a.mdx)(i.C,{to:"examples/tutorials/basic/your_first_hydra_app/4_config_groups",mdxType:"ExampleGithubLink"}),(0,a.mdx)("p",null,"Suppose you want to benchmark your application on each of PostgreSQL and MySQL. To do this, use config groups. "),(0,a.mdx)("p",null,"A ",(0,a.mdx)("em",{parentName:"p"},(0,a.mdx)("strong",{parentName:"em"},"Config Group"))," is a named group with a set of valid options.\nSelecting a non-existent config option generates an error message with the valid options."),(0,a.mdx)("h3",{id:"creating-config-groups"},"Creating config groups"),(0,a.mdx)("p",null,"To create a config group, create a directory, e.g. ",(0,a.mdx)("inlineCode",{parentName:"p"},"db"),", to hold a file for each database configuration option.\nSince we are expecting to have multiple config groups, we will proactively move all the configuration files\ninto a ",(0,a.mdx)("inlineCode",{parentName:"p"},"conf")," directory."),(0,a.mdx)("div",{className:"row"},(0,a.mdx)("div",{className:"col col--4"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Directory layout"',title:'"Directory','layout"':!0},"\u251c\u2500 conf\n\u2502 \u2514\u2500 db\n\u2502 \u251c\u2500 mysql.yaml\n\u2502 \u2514\u2500 postgresql.yaml\n\u2514\u2500\u2500 my_app.py\n"))),(0,a.mdx)("div",{className:"col col--4"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml"',title:'"db/mysql.yaml"'},"driver: mysql\nuser: omry\npassword: secret\n\n\n"))),(0,a.mdx)("div",{className:"col col--4"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/postgresql.yaml"',title:'"db/postgresql.yaml"'},"driver: postgresql\nuser: postgres_user\npassword: drowssap\ntimeout: 10\n\n")))),(0,a.mdx)("h3",{id:"using-config-groups"},"Using config groups"),(0,a.mdx)("p",null,"Since we moved all the configs into the ",(0,a.mdx)("inlineCode",{parentName:"p"},"conf")," directory, we need to tell Hydra where to find them using the ",(0,a.mdx)("inlineCode",{parentName:"p"},"config_path")," parameter.\n",(0,a.mdx)("strong",{parentName:"p"},(0,a.mdx)("inlineCode",{parentName:"strong"},"config_path")," is a directory relative to ",(0,a.mdx)("inlineCode",{parentName:"strong"},"my_app.py")),"."),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app.py" {4}',title:'"my_app.py"',"{4}":!0},'from omegaconf import DictConfig, OmegaConf\nimport hydra\n\n@hydra.main(config_path="conf")\ndef my_app(cfg: DictConfig) -> None:\n print(OmegaConf.to_yaml(cfg))\n\nif __name__ == "__main__":\n my_app()\n')),(0,a.mdx)("p",null,"Running ",(0,a.mdx)("inlineCode",{parentName:"p"},"my_app.py")," without requesting a configuration will print an empty config."),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py\n{}\n")),(0,a.mdx)("p",null,"Select an item from a config group with ",(0,a.mdx)("inlineCode",{parentName:"p"},"+GROUP=OPTION"),", e.g: "),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{2}","{2}":!0},"$ python my_app.py +db=postgresql\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 10\n user: postgres_user\n")),(0,a.mdx)("p",null,"By default, the config group determines where the config content is placed inside the final config object.\nIn Hydra, the path to the config content is referred to as the config ",(0,a.mdx)("inlineCode",{parentName:"p"},"package"),".\nThe package of ",(0,a.mdx)("inlineCode",{parentName:"p"},"db/postgresql.yaml")," is ",(0,a.mdx)("inlineCode",{parentName:"p"},"db"),":"),(0,a.mdx)("p",null,"Like before, you can still override individual values in the resulting config:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py +db=postgresql db.timeout=20\ndb:\n driver: postgresql\n pass: drowssap\n timeout: 20\n user: postgres_user\n")),(0,a.mdx)("h3",{id:"advanced-topics"},"Advanced topics"),(0,a.mdx)("ul",null,(0,a.mdx)("li",{parentName:"ul"},"Config content can be relocated via package overrides. See ",(0,a.mdx)("a",{parentName:"li",href:"/docs/1.1/advanced/overriding_packages"},"Reference Manual/Packages"),". "),(0,a.mdx)("li",{parentName:"ul"},"Multiple options can be selected from the same Config Group by specifying them as a list.",(0,a.mdx)("br",{parentName:"li"}),"See ",(0,a.mdx)("a",{parentName:"li",href:"/docs/1.1/patterns/select_multiple_configs_from_config_group"},"Common Patterns/Selecting multiple configs from a Config Group"))))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/356d2c93.9e28bfd2.js b/assets/js/356d2c93.9e28bfd2.js new file mode 100644 index 0000000000..1555798a25 --- /dev/null +++ b/assets/js/356d2c93.9e28bfd2.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[1572],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>p,MDXProvider:()=>u,mdx:()=>h,useMDXComponents:()=>m,withMDXComponents:()=>s});var a=t(96540);function i(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function r(){return r=Object.assign||function(e){for(var n=1;n=0||(i[t]=e[t]);return i}(e,n);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(i[t]=e[t])}return i}var p=a.createContext({}),s=function(e){return function(n){var t=m(n.components);return a.createElement(e,r({},n,{components:t}))}},m=function(e){var n=a.useContext(p),t=n;return e&&(t="function"==typeof e?e(n):o(o({},n),e)),t},u=function(e){var n=m(e.components);return a.createElement(p.Provider,{value:n},e.children)},c={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},g=a.forwardRef((function(e,n){var t=e.components,i=e.mdxType,r=e.originalType,l=e.parentName,p=d(e,["components","mdxType","originalType","parentName"]),s=m(t),u=i,g=s["".concat(l,".").concat(u)]||s[u]||c[u]||r;return t?a.createElement(g,o(o({ref:n},p),{},{components:t})):a.createElement(g,o({ref:n},p))}));function h(e,n){var t=arguments,i=n&&n.mdxType;if("string"==typeof e||i){var r=t.length,l=new Array(r);l[0]=g;var o={};for(var d in n)hasOwnProperty.call(n,d)&&(o[d]=n[d]);o.originalType=e,o.mdxType="string"==typeof e?e:i,l[1]=o;for(var p=2;p{t.d(n,{A:()=>d,C:()=>p});var a=t(58168),i=t(96540),r=t(75489),l=t(44586),o=t(74098);function d(e){return i.createElement(r.default,(0,a.A)({},e,{to:(n=e.to,d=(0,o.useActiveVersion)(),(0,l.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==d?void 0:d.name)?t:"current"]+n),target:"_blank"}));var n,t,d}function p(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return i.createElement(d,e,i.createElement("span",null,"\xa0"),i.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},86629:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>p,default:()=>c,frontMatter:()=>d,metadata:()=>s,toc:()=>m});var a=t(58168),i=t(98587),r=(t(96540),t(15680)),l=t(49595),o=["components"],d={id:"develop",title:"Plugin development",sidebar_label:"Plugin development"},p=void 0,s={unversionedId:"advanced/plugins/develop",id:"version-1.1/advanced/plugins/develop",title:"Plugin development",description:"If you develop plugins, please join the Plugin developer announcement chat channel.",source:"@site/versioned_docs/version-1.1/advanced/plugins/develop.md",sourceDirName:"advanced/plugins",slug:"/advanced/plugins/develop",permalink:"/docs/1.1/advanced/plugins/develop",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/advanced/plugins/develop.md",tags:[],version:"1.1",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"develop",title:"Plugin development",sidebar_label:"Plugin development"},sidebar:"version-1.1/docs",previous:{title:"Plugins Overview",permalink:"/docs/1.1/advanced/plugins/overview"},next:{title:"Application packaging",permalink:"/docs/1.1/advanced/app_packaging"}},m=[{value:"Plugin discovery process",id:"plugin-discovery-process",children:[],level:2},{value:"Getting started",id:"getting-started",children:[],level:2}],u={toc:m};function c(e){var n=e.components,t=(0,i.A)(e,o);return(0,r.mdx)("wrapper",(0,a.A)({},u,t,{components:n,mdxType:"MDXLayout"}),(0,r.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,r.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,r.mdx)("h5",{parentName:"div"},(0,r.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,r.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,r.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"info")),(0,r.mdx)("div",{parentName:"div",className:"admonition-content"},(0,r.mdx)("p",{parentName:"div"},"If you develop plugins, please join the ",(0,r.mdx)("a",{href:"https://hydra-framework.zulipchat.com/#narrow/stream/233935-Hydra-plugin.20dev.20announcements"},"Plugin developer announcement chat channel"),"."))),(0,r.mdx)("p",null,"When developing Hydra plugins, keep the following things in mind:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Hydra plugins can be either a standalone Python package, or a part of your existing Python package.\nIn both cases - They should be in the namespace module ",(0,r.mdx)("inlineCode",{parentName:"li"},"hydra_plugins")," (This is a top level module, Your plugin will ",(0,r.mdx)("strong",{parentName:"li"},"NOT")," be discovered if you place it in ",(0,r.mdx)("inlineCode",{parentName:"li"},"mylib.hydra_plugins"),")."),(0,r.mdx)("li",{parentName:"ul"},"Do ",(0,r.mdx)("strong",{parentName:"li"},"NOT")," place an ",(0,r.mdx)("inlineCode",{parentName:"li"},"__init__.py")," file in ",(0,r.mdx)("inlineCode",{parentName:"li"},"hydra_plugins")," (doing so may break other installed Hydra plugins).")),(0,r.mdx)("h2",{id:"plugin-discovery-process"},"Plugin discovery process"),(0,r.mdx)("p",null,"The plugin discovery process runs whenever Hydra starts. During plugin discovery, Hydra scans for plugins in all the submodules of ",(0,r.mdx)("inlineCode",{parentName:"p"},"hydra_plugins"),". Hydra will import each module and look for plugins defined in that module.\nAny module under ",(0,r.mdx)("inlineCode",{parentName:"p"},"hydra_plugins")," that is slow to import will slow down the startup of ",(0,r.mdx)("strong",{parentName:"p"},"ALL")," Hydra applications.\nPlugins with expensive imports can exclude individual files from Hydra's plugin discovery process by prefixing them with ",(0,r.mdx)("inlineCode",{parentName:"p"},"_")," (but not ",(0,r.mdx)("inlineCode",{parentName:"p"},"__"),").\nFor example, the file ",(0,r.mdx)("inlineCode",{parentName:"p"},"_my_plugin_lib.py")," would not be imported and scanned, while ",(0,r.mdx)("inlineCode",{parentName:"p"},"my_plugin_lib.py")," would be."),(0,r.mdx)("h2",{id:"getting-started"},"Getting started"),(0,r.mdx)("p",null,"The best way to get started developing a Hydra plugin is to base your new plugin on one of the example plugins:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Copy the subtree of the relevant ",(0,r.mdx)(l.A,{to:"examples/plugins",mdxType:"GithubLink"},"example plugin")," into a standalone project."),(0,r.mdx)("li",{parentName:"ul"},"Edit ",(0,r.mdx)("inlineCode",{parentName:"li"},"setup.py"),", rename the plugin module, for example from ",(0,r.mdx)("inlineCode",{parentName:"li"},"hydra_plugins.example_xyz_plugin")," to ",(0,r.mdx)("inlineCode",{parentName:"li"},"hydra_plugins.my_xyz_plugin"),"."),(0,r.mdx)("li",{parentName:"ul"},"Install the new plugin (Run this in the plugin directory: ",(0,r.mdx)("inlineCode",{parentName:"li"},"pip install -e ."),")"),(0,r.mdx)("li",{parentName:"ul"},"Run the included example app and make sure that the plugin is discovered:")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-shell"},"$ python example/my_app.py --info plugins\nInstalled Hydra Plugins\n***********************\n ...\n Launcher:\n ---------\n MyLauncher\n ...\n")),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Run the example application to see that that your plugin is doing something."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("em",{parentName:"li"},"[Optional]")," If you want the plugin be embedded in your existing application/library, move the ",(0,r.mdx)("inlineCode",{parentName:"li"},"hydra_plugins")," directory\nand make sure that it's included as a namespace module in your final Python package. See the ",(0,r.mdx)("inlineCode",{parentName:"li"},"setup.py"),"\nfile included with the example plugin for hints (typically this involves using ",(0,r.mdx)("inlineCode",{parentName:"li"},'find_namespace_packages(include=["hydra_plugins.*"])'),")."),(0,r.mdx)("li",{parentName:"ul"},"Hack on your plugin, Ensure that the recommended tests and any tests you want to add are passing.")))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/356d2c93.c57948b6.js b/assets/js/356d2c93.c57948b6.js deleted file mode 100644 index 52b19ceb40..0000000000 --- a/assets/js/356d2c93.c57948b6.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[1572],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>p,MDXProvider:()=>u,mdx:()=>h,useMDXComponents:()=>m,withMDXComponents:()=>s});var a=t(96540);function i(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function r(){return r=Object.assign||function(e){for(var n=1;n=0||(i[t]=e[t]);return i}(e,n);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(i[t]=e[t])}return i}var p=a.createContext({}),s=function(e){return function(n){var t=m(n.components);return a.createElement(e,r({},n,{components:t}))}},m=function(e){var n=a.useContext(p),t=n;return e&&(t="function"==typeof e?e(n):o(o({},n),e)),t},u=function(e){var n=m(e.components);return a.createElement(p.Provider,{value:n},e.children)},c={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},g=a.forwardRef((function(e,n){var t=e.components,i=e.mdxType,r=e.originalType,l=e.parentName,p=d(e,["components","mdxType","originalType","parentName"]),s=m(t),u=i,g=s["".concat(l,".").concat(u)]||s[u]||c[u]||r;return t?a.createElement(g,o(o({ref:n},p),{},{components:t})):a.createElement(g,o({ref:n},p))}));function h(e,n){var t=arguments,i=n&&n.mdxType;if("string"==typeof e||i){var r=t.length,l=new Array(r);l[0]=g;var o={};for(var d in n)hasOwnProperty.call(n,d)&&(o[d]=n[d]);o.originalType=e,o.mdxType="string"==typeof e?e:i,l[1]=o;for(var p=2;p{t.d(n,{A:()=>d,C:()=>p});var a=t(58168),i=t(96540),r=t(75489),l=t(44586),o=t(74098);function d(e){return i.createElement(r.default,(0,a.A)({},e,{to:(n=e.to,d=(0,o.useActiveVersion)(),(0,l.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==d?void 0:d.name)?t:"current"]+n),target:"_blank"}));var n,t,d}function p(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return i.createElement(d,e,i.createElement("span",null,"\xa0"),i.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},86629:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>p,default:()=>c,frontMatter:()=>d,metadata:()=>s,toc:()=>m});var a=t(58168),i=t(98587),r=(t(96540),t(15680)),l=t(49595),o=["components"],d={id:"develop",title:"Plugin development",sidebar_label:"Plugin development"},p=void 0,s={unversionedId:"advanced/plugins/develop",id:"version-1.1/advanced/plugins/develop",title:"Plugin development",description:"If you develop plugins, please join the Plugin developer announcement chat channel.",source:"@site/versioned_docs/version-1.1/advanced/plugins/develop.md",sourceDirName:"advanced/plugins",slug:"/advanced/plugins/develop",permalink:"/docs/1.1/advanced/plugins/develop",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/advanced/plugins/develop.md",tags:[],version:"1.1",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"develop",title:"Plugin development",sidebar_label:"Plugin development"},sidebar:"version-1.1/docs",previous:{title:"Plugins Overview",permalink:"/docs/1.1/advanced/plugins/overview"},next:{title:"Application packaging",permalink:"/docs/1.1/advanced/app_packaging"}},m=[{value:"Plugin discovery process",id:"plugin-discovery-process",children:[],level:2},{value:"Getting started",id:"getting-started",children:[],level:2}],u={toc:m};function c(e){var n=e.components,t=(0,i.A)(e,o);return(0,r.mdx)("wrapper",(0,a.A)({},u,t,{components:n,mdxType:"MDXLayout"}),(0,r.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,r.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,r.mdx)("h5",{parentName:"div"},(0,r.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,r.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,r.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"info")),(0,r.mdx)("div",{parentName:"div",className:"admonition-content"},(0,r.mdx)("p",{parentName:"div"},"If you develop plugins, please join the ",(0,r.mdx)("a",{href:"https://hydra-framework.zulipchat.com/#narrow/stream/233935-Hydra-plugin.20dev.20announcements"},"Plugin developer announcement chat channel"),"."))),(0,r.mdx)("p",null,"When developing Hydra plugins, keep the following things in mind:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Hydra plugins can be either a standalone Python package, or a part of your existing Python package.\nIn both cases - They should be in the namespace module ",(0,r.mdx)("inlineCode",{parentName:"li"},"hydra_plugins")," (This is a top level module, Your plugin will ",(0,r.mdx)("strong",{parentName:"li"},"NOT")," be discovered if you place it in ",(0,r.mdx)("inlineCode",{parentName:"li"},"mylib.hydra_plugins"),")."),(0,r.mdx)("li",{parentName:"ul"},"Do ",(0,r.mdx)("strong",{parentName:"li"},"NOT")," place an ",(0,r.mdx)("inlineCode",{parentName:"li"},"__init__.py")," file in ",(0,r.mdx)("inlineCode",{parentName:"li"},"hydra_plugins")," (doing so may break other installed Hydra plugins).")),(0,r.mdx)("h2",{id:"plugin-discovery-process"},"Plugin discovery process"),(0,r.mdx)("p",null,"The plugin discovery process runs whenever Hydra starts. During plugin discovery, Hydra scans for plugins in all the submodules of ",(0,r.mdx)("inlineCode",{parentName:"p"},"hydra_plugins"),". Hydra will import each module and look for plugins defined in that module.\nAny module under ",(0,r.mdx)("inlineCode",{parentName:"p"},"hydra_plugins")," that is slow to import will slow down the startup of ",(0,r.mdx)("strong",{parentName:"p"},"ALL")," Hydra applications.\nPlugins with expensive imports can exclude individual files from Hydra's plugin discovery process by prefixing them with ",(0,r.mdx)("inlineCode",{parentName:"p"},"_")," (but not ",(0,r.mdx)("inlineCode",{parentName:"p"},"__"),").\nFor example, the file ",(0,r.mdx)("inlineCode",{parentName:"p"},"_my_plugin_lib.py")," would not be imported and scanned, while ",(0,r.mdx)("inlineCode",{parentName:"p"},"my_plugin_lib.py")," would be."),(0,r.mdx)("h2",{id:"getting-started"},"Getting started"),(0,r.mdx)("p",null,"The best way to get started developing a Hydra plugin is to base your new plugin on one of the example plugins:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Copy the subtree of the relevant ",(0,r.mdx)(l.A,{to:"examples/plugins",mdxType:"GithubLink"},"example plugin")," into a standalone project."),(0,r.mdx)("li",{parentName:"ul"},"Edit ",(0,r.mdx)("inlineCode",{parentName:"li"},"setup.py"),", rename the plugin module, for example from ",(0,r.mdx)("inlineCode",{parentName:"li"},"hydra_plugins.example_xyz_plugin")," to ",(0,r.mdx)("inlineCode",{parentName:"li"},"hydra_plugins.my_xyz_plugin"),"."),(0,r.mdx)("li",{parentName:"ul"},"Install the new plugin (Run this in the plugin directory: ",(0,r.mdx)("inlineCode",{parentName:"li"},"pip install -e ."),")"),(0,r.mdx)("li",{parentName:"ul"},"Run the included example app and make sure that the plugin is discovered:")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-shell"},"$ python example/my_app.py --info plugins\nInstalled Hydra Plugins\n***********************\n ...\n Launcher:\n ---------\n MyLauncher\n ...\n")),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Run the example application to see that that your plugin is doing something."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("em",{parentName:"li"},"[Optional]")," If you want the plugin be embedded in your existing application/library, move the ",(0,r.mdx)("inlineCode",{parentName:"li"},"hydra_plugins")," directory\nand make sure that it's included as a namespace module in your final Python package. See the ",(0,r.mdx)("inlineCode",{parentName:"li"},"setup.py"),"\nfile included with the example plugin for hints (typically this involves using ",(0,r.mdx)("inlineCode",{parentName:"li"},'find_namespace_packages(include=["hydra_plugins.*"])'),")."),(0,r.mdx)("li",{parentName:"ul"},"Hack on your plugin, Ensure that the recommended tests and any tests you want to add are passing.")))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/35935476.403b0ae4.js b/assets/js/35935476.403b0ae4.js deleted file mode 100644 index 504d2962c6..0000000000 --- a/assets/js/35935476.403b0ae4.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3567],{15680:(e,a,n)=>{n.r(a),n.d(a,{MDXContext:()=>l,MDXProvider:()=>m,mdx:()=>f,useMDXComponents:()=>s,withMDXComponents:()=>d});var t=n(96540);function r(e,a,n){return a in e?Object.defineProperty(e,a,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[a]=n,e}function p(){return p=Object.assign||function(e){for(var a=1;a=0||(r[n]=e[n]);return r}(e,a);if(Object.getOwnPropertySymbols){var p=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var l=t.createContext({}),d=function(e){return function(a){var n=s(a.components);return t.createElement(e,p({},a,{components:n}))}},s=function(e){var a=t.useContext(l),n=a;return e&&(n="function"==typeof e?e(a):o(o({},a),e)),n},m=function(e){var a=s(e.components);return t.createElement(l.Provider,{value:a},e.children)},u={inlineCode:"code",wrapper:function(e){var a=e.children;return t.createElement(t.Fragment,{},a)}},g=t.forwardRef((function(e,a){var n=e.components,r=e.mdxType,p=e.originalType,i=e.parentName,l=c(e,["components","mdxType","originalType","parentName"]),d=s(n),m=r,g=d["".concat(i,".").concat(m)]||d[m]||u[m]||p;return n?t.createElement(g,o(o({ref:a},l),{},{components:n})):t.createElement(g,o({ref:a},l))}));function f(e,a){var n=arguments,r=a&&a.mdxType;if("string"==typeof e||r){var p=n.length,i=new Array(p);i[0]=g;var o={};for(var c in a)hasOwnProperty.call(a,c)&&(o[c]=a[c]);o.originalType=e,o.mdxType="string"==typeof e?e:r,i[1]=o;for(var l=2;l{n.r(a),n.d(a,{contentTitle:()=>c,default:()=>m,frontMatter:()=>o,metadata:()=>l,toc:()=>d});var t=n(58168),r=n(98587),p=(n(96540),n(15680)),i=["components"],o={id:"app_packaging",title:"Application packaging",sidebar_label:"Application packaging"},c=void 0,l={unversionedId:"advanced/app_packaging",id:"version-1.0/advanced/app_packaging",title:"Application packaging",description:"Example application",source:"@site/versioned_docs/version-1.0/advanced/packaging.md",sourceDirName:"advanced",slug:"/advanced/app_packaging",permalink:"/docs/1.0/advanced/app_packaging",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.0/advanced/packaging.md",tags:[],version:"1.0",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"app_packaging",title:"Application packaging",sidebar_label:"Application packaging"},sidebar:"version-1.0/docs",previous:{title:"Hydra plugins",permalink:"/docs/1.0/advanced/plugins"},next:{title:"Hydra in Jupyter Notebooks",permalink:"/docs/1.0/advanced/jupyter_notebooks"}},d=[],s={toc:d};function m(e){var a=e.components,n=(0,r.A)(e,i);return(0,p.mdx)("wrapper",(0,t.A)({},s,n,{components:a,mdxType:"MDXLayout"}),(0,p.mdx)("p",null,(0,p.mdx)("a",{parentName:"p",href:"https://github.com/facebookresearch/hydra/tree/1.0_branch/examples/advanced/hydra_app_example"},(0,p.mdx)("img",{parentName:"a",src:"https://img.shields.io/badge/-Example%20application-informational",alt:"Example application"}))),(0,p.mdx)("p",null,"You can package your Hydra application along with its configuration.\nThere is a working example ",(0,p.mdx)("a",{parentName:"p",href:"https://github.com/facebookresearch/hydra/tree/1.0_branch/examples/advanced/hydra_app_example"},"here"),"."),(0,p.mdx)("p",null,"You can run it with:"),(0,p.mdx)("pre",null,(0,p.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python examples/advanced/hydra_app_example/hydra_app/main.py\ndataset:\n name: imagenet\n path: /datasets/imagenet\n")),(0,p.mdx)("p",null,"To install it, use:"),(0,p.mdx)("pre",null,(0,p.mdx)("code",{parentName:"pre",className:"language-text"},"$ pip install examples/advanced/hydra_app_example\n...\nSuccessfully installed hydra-app-0.1\n")),(0,p.mdx)("p",null,"Run the installed app with:"),(0,p.mdx)("pre",null,(0,p.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ hydra_app\ndataset:\n name: imagenet\n path: /datasets/imagenet\n")),(0,p.mdx)("p",null,"The installed app will use the packaged configuration files."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/35935476.47a1ce8d.js b/assets/js/35935476.47a1ce8d.js new file mode 100644 index 0000000000..b9f00c4ce1 --- /dev/null +++ b/assets/js/35935476.47a1ce8d.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3567],{15680:(e,a,n)=>{n.r(a),n.d(a,{MDXContext:()=>l,MDXProvider:()=>m,mdx:()=>f,useMDXComponents:()=>s,withMDXComponents:()=>d});var t=n(96540);function r(e,a,n){return a in e?Object.defineProperty(e,a,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[a]=n,e}function p(){return p=Object.assign||function(e){for(var a=1;a=0||(r[n]=e[n]);return r}(e,a);if(Object.getOwnPropertySymbols){var p=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var l=t.createContext({}),d=function(e){return function(a){var n=s(a.components);return t.createElement(e,p({},a,{components:n}))}},s=function(e){var a=t.useContext(l),n=a;return e&&(n="function"==typeof e?e(a):i(i({},a),e)),n},m=function(e){var a=s(e.components);return t.createElement(l.Provider,{value:a},e.children)},u={inlineCode:"code",wrapper:function(e){var a=e.children;return t.createElement(t.Fragment,{},a)}},g=t.forwardRef((function(e,a){var n=e.components,r=e.mdxType,p=e.originalType,o=e.parentName,l=c(e,["components","mdxType","originalType","parentName"]),d=s(n),m=r,g=d["".concat(o,".").concat(m)]||d[m]||u[m]||p;return n?t.createElement(g,i(i({ref:a},l),{},{components:n})):t.createElement(g,i({ref:a},l))}));function f(e,a){var n=arguments,r=a&&a.mdxType;if("string"==typeof e||r){var p=n.length,o=new Array(p);o[0]=g;var i={};for(var c in a)hasOwnProperty.call(a,c)&&(i[c]=a[c]);i.originalType=e,i.mdxType="string"==typeof e?e:r,o[1]=i;for(var l=2;l{n.r(a),n.d(a,{contentTitle:()=>c,default:()=>m,frontMatter:()=>i,metadata:()=>l,toc:()=>d});var t=n(58168),r=n(98587),p=(n(96540),n(15680)),o=["components"],i={id:"app_packaging",title:"Application packaging",sidebar_label:"Application packaging"},c=void 0,l={unversionedId:"advanced/app_packaging",id:"version-1.0/advanced/app_packaging",title:"Application packaging",description:"Example application",source:"@site/versioned_docs/version-1.0/advanced/packaging.md",sourceDirName:"advanced",slug:"/advanced/app_packaging",permalink:"/docs/1.0/advanced/app_packaging",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.0/advanced/packaging.md",tags:[],version:"1.0",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"app_packaging",title:"Application packaging",sidebar_label:"Application packaging"},sidebar:"version-1.0/docs",previous:{title:"Hydra plugins",permalink:"/docs/1.0/advanced/plugins"},next:{title:"Hydra in Jupyter Notebooks",permalink:"/docs/1.0/advanced/jupyter_notebooks"}},d=[],s={toc:d};function m(e){var a=e.components,n=(0,r.A)(e,o);return(0,p.mdx)("wrapper",(0,t.A)({},s,n,{components:a,mdxType:"MDXLayout"}),(0,p.mdx)("p",null,(0,p.mdx)("a",{parentName:"p",href:"https://github.com/facebookresearch/hydra/tree/1.0_branch/examples/advanced/hydra_app_example"},(0,p.mdx)("img",{parentName:"a",src:"https://img.shields.io/badge/-Example%20application-informational",alt:"Example application"}))),(0,p.mdx)("p",null,"You can package your Hydra application along with its configuration.\nThere is a working example ",(0,p.mdx)("a",{parentName:"p",href:"https://github.com/facebookresearch/hydra/tree/1.0_branch/examples/advanced/hydra_app_example"},"here"),"."),(0,p.mdx)("p",null,"You can run it with:"),(0,p.mdx)("pre",null,(0,p.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python examples/advanced/hydra_app_example/hydra_app/main.py\ndataset:\n name: imagenet\n path: /datasets/imagenet\n")),(0,p.mdx)("p",null,"To install it, use:"),(0,p.mdx)("pre",null,(0,p.mdx)("code",{parentName:"pre",className:"language-text"},"$ pip install examples/advanced/hydra_app_example\n...\nSuccessfully installed hydra-app-0.1\n")),(0,p.mdx)("p",null,"Run the installed app with:"),(0,p.mdx)("pre",null,(0,p.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ hydra_app\ndataset:\n name: imagenet\n path: /datasets/imagenet\n")),(0,p.mdx)("p",null,"The installed app will use the packaged configuration files."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/35af814a.39a12da6.js b/assets/js/35af814a.39a12da6.js new file mode 100644 index 0000000000..b1bf2b3679 --- /dev/null +++ b/assets/js/35af814a.39a12da6.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[9670],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>l,MDXProvider:()=>m,mdx:()=>f,useMDXComponents:()=>p,withMDXComponents:()=>d});var a=t(96540);function o(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function r(){return r=Object.assign||function(e){for(var n=1;n=0||(o[t]=e[t]);return o}(e,n);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(o[t]=e[t])}return o}var l=a.createContext({}),d=function(e){return function(n){var t=p(n.components);return a.createElement(e,r({},n,{components:t}))}},p=function(e){var n=a.useContext(l),t=n;return e&&(t="function"==typeof e?e(n):s(s({},n),e)),t},m=function(e){var n=p(e.components);return a.createElement(l.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},g=a.forwardRef((function(e,n){var t=e.components,o=e.mdxType,r=e.originalType,i=e.parentName,l=c(e,["components","mdxType","originalType","parentName"]),d=p(t),m=o,g=d["".concat(i,".").concat(m)]||d[m]||u[m]||r;return t?a.createElement(g,s(s({ref:n},l),{},{components:t})):a.createElement(g,s({ref:n},l))}));function f(e,n){var t=arguments,o=n&&n.mdxType;if("string"==typeof e||o){var r=t.length,i=new Array(r);i[0]=g;var s={};for(var c in n)hasOwnProperty.call(n,c)&&(s[c]=n[c]);s.originalType=e,s.mdxType="string"==typeof e?e:o,i[1]=s;for(var l=2;l{t.d(n,{A:()=>c,C:()=>l});var a=t(58168),o=t(96540),r=t(75489),i=t(44586),s=t(74098);function c(e){return o.createElement(r.default,(0,a.A)({},e,{to:(n=e.to,c=(0,s.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==c?void 0:c.name)?t:"current"]+n),target:"_blank"}));var n,t,c}function l(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return o.createElement(c,e,o.createElement("span",null,"\xa0"),o.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},71906:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>l,default:()=>u,frontMatter:()=>c,metadata:()=>d,toc:()=>p});var a=t(58168),o=t(98587),r=(t(96540),t(15680)),i=t(49595),s=["components"],c={id:"config_groups",title:"Config Groups"},l=void 0,d={unversionedId:"tutorials/structured_config/config_groups",id:"tutorials/structured_config/config_groups",title:"Config Groups",description:"Structured Configs can be used to implement config groups. Special care needs to be taken when specifying a",source:"@site/docs/tutorials/structured_config/3_config_groups.md",sourceDirName:"tutorials/structured_config",slug:"/tutorials/structured_config/config_groups",permalink:"/docs/tutorials/structured_config/config_groups",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/tutorials/structured_config/3_config_groups.md",tags:[],version:"current",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:3,frontMatter:{id:"config_groups",title:"Config Groups"},sidebar:"docs",previous:{title:"A hierarchical static configuration",permalink:"/docs/tutorials/structured_config/hierarchical_static_config"},next:{title:"Defaults List",permalink:"/docs/tutorials/structured_config/defaults"}},p=[{value:"Config inheritance",id:"config-inheritance",children:[],level:3},{value:"Missing fields",id:"missing-fields",children:[],level:3}],m={toc:p};function u(e){var n=e.components,t=(0,o.A)(e,s);return(0,r.mdx)("wrapper",(0,a.A)({},m,t,{components:n,mdxType:"MDXLayout"}),(0,r.mdx)(i.C,{to:"examples/tutorials/structured_configs/3_config_groups/my_app.py",mdxType:"ExampleGithubLink"}),(0,r.mdx)("p",null,"Structured Configs can be used to implement config groups. Special care needs to be taken when specifying a\ndefault value for fields populated by a config group. We will look at why below."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Defining a config group for database" {16-17,22-23}',title:'"Defining',a:!0,config:!0,group:!0,for:!0,'database"':!0,"{16-17,22-23}":!0},'from dataclasses import dataclass\n\nimport hydra\nfrom hydra.core.config_store import ConfigStore\n\n@dataclass\nclass MySQLConfig:\n driver: str = "mysql"\n host: str = "localhost"\n port: int = 3306\n\n@dataclass\nclass PostGreSQLConfig:\n driver: str = "postgresql"\n host: str = "localhost"\n port: int = 5432\n timeout: int = 10\n\n@dataclass\nclass Config:\n # We will populate db using composition.\n db: Any\n\n# Create config group `db` with options \'mysql\' and \'postgreqsl\'\ncs = ConfigStore.instance()\ncs.store(name="config", node=Config)\ncs.store(group="db", name="mysql", node=MySQLConfig)\ncs.store(group="db", name="postgresql", node=PostGreSQLConfig)\n\n@hydra.main(version_base=None, config_name="config")\ndef my_app(cfg: Config) -> None:\n print(OmegaConf.to_yaml(cfg))\n\nif __name__ == "__main__":\n my_app()\n')),(0,r.mdx)("div",{className:"admonition admonition-caution alert alert--warning"},(0,r.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,r.mdx)("h5",{parentName:"div"},(0,r.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,r.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"16",height:"16",viewBox:"0 0 16 16"},(0,r.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"}))),"caution")),(0,r.mdx)("div",{parentName:"div",className:"admonition-content"},(0,r.mdx)("p",{parentName:"div"},"The ",(0,r.mdx)("em",{parentName:"p"},"Config")," class is ",(0,r.mdx)("strong",{parentName:"p"},"NOT")," the Defaults list. We will see the Defaults list in the next page."))),(0,r.mdx)("p",null,"You can select the database from the command line:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py +db=postgresql\ndb:\n driver: postgresql\n host: localhost\n password: drowssap\n port: 5432\n timeout: 10\n user: postgres_user\n")),(0,r.mdx)("p",null,"The ",(0,r.mdx)("inlineCode",{parentName:"p"},"+")," above is required because there is no default choice for the config group ",(0,r.mdx)("inlineCode",{parentName:"p"},"db"),".\nThe next page will reintroduce the Defaults List, eliminating the need for the ",(0,r.mdx)("inlineCode",{parentName:"p"},"+"),"."),(0,r.mdx)("h3",{id:"config-inheritance"},"Config inheritance"),(0,r.mdx)(i.C,{to:"examples/tutorials/structured_configs/3_config_groups/my_app_with_inheritance.py",mdxType:"ExampleGithubLink"}),(0,r.mdx)("p",null,"Standard Python inheritance can be used to get improved type safety, and to move common fields to the parent class."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Defining a config group for database using inheritance"',title:'"Defining',a:!0,config:!0,group:!0,for:!0,database:!0,using:!0,'inheritance"':!0},'from omegaconf import MISSING\n\n@dataclass\nclass DBConfig:\n host: str = "localhost"\n port: int = MISSING\n driver: str = MISSING\n\n@dataclass\nclass MySQLConfig(DBConfig):\n driver: str = "mysql"\n port: int = 3306\n\n@dataclass\nclass PostGreSQLConfig(DBConfig):\n driver: str = "postgresql"\n port: int = 5432\n timeout: int = 10\n\n@dataclass\nclass Config:\n # We can now annotate db as DBConfig which\n # improves both static and dynamic type safety.\n db: DBConfig\n')),(0,r.mdx)("h3",{id:"missing-fields"},"Missing fields"),(0,r.mdx)("p",null,"Assign ",(0,r.mdx)("em",{parentName:"p"},"MISSING")," to a field to indicates that it does not have a default value. This is equivalent to\nthe ",(0,r.mdx)("inlineCode",{parentName:"p"},"???")," literal we have seen in OmegaConf configs before."),(0,r.mdx)("p",null,"Omitting a default value is equivalent to assigning ",(0,r.mdx)("em",{parentName:"p"},"MISSING")," to it, although it is sometimes\nconvenient to be able to assign MISSING it to a field."),(0,r.mdx)("div",{className:"admonition admonition-caution alert alert--warning"},(0,r.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,r.mdx)("h5",{parentName:"div"},(0,r.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,r.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"16",height:"16",viewBox:"0 0 16 16"},(0,r.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"}))),"caution")),(0,r.mdx)("div",{parentName:"div",className:"admonition-content"},(0,r.mdx)("p",{parentName:"div"},"Do not confuse ",(0,r.mdx)("strong",{parentName:"p"},"omegaconf.MISSING")," with ",(0,r.mdx)("strong",{parentName:"p"},"dataclass.MISSING"),"."))))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/35af814a.7a4429e6.js b/assets/js/35af814a.7a4429e6.js deleted file mode 100644 index 299cf53bbc..0000000000 --- a/assets/js/35af814a.7a4429e6.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[9670],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>l,MDXProvider:()=>m,mdx:()=>f,useMDXComponents:()=>p,withMDXComponents:()=>d});var a=t(96540);function o(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(o[t]=e[t]);return o}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(o[t]=e[t])}return o}var l=a.createContext({}),d=function(e){return function(n){var t=p(n.components);return a.createElement(e,i({},n,{components:t}))}},p=function(e){var n=a.useContext(l),t=n;return e&&(t="function"==typeof e?e(n):s(s({},n),e)),t},m=function(e){var n=p(e.components);return a.createElement(l.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},g=a.forwardRef((function(e,n){var t=e.components,o=e.mdxType,i=e.originalType,r=e.parentName,l=c(e,["components","mdxType","originalType","parentName"]),d=p(t),m=o,g=d["".concat(r,".").concat(m)]||d[m]||u[m]||i;return t?a.createElement(g,s(s({ref:n},l),{},{components:t})):a.createElement(g,s({ref:n},l))}));function f(e,n){var t=arguments,o=n&&n.mdxType;if("string"==typeof e||o){var i=t.length,r=new Array(i);r[0]=g;var s={};for(var c in n)hasOwnProperty.call(n,c)&&(s[c]=n[c]);s.originalType=e,s.mdxType="string"==typeof e?e:o,r[1]=s;for(var l=2;l{t.d(n,{A:()=>c,C:()=>l});var a=t(58168),o=t(96540),i=t(75489),r=t(44586),s=t(74098);function c(e){return o.createElement(i.default,(0,a.A)({},e,{to:(n=e.to,c=(0,s.useActiveVersion)(),(0,r.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==c?void 0:c.name)?t:"current"]+n),target:"_blank"}));var n,t,c}function l(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return o.createElement(c,e,o.createElement("span",null,"\xa0"),o.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},71906:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>l,default:()=>u,frontMatter:()=>c,metadata:()=>d,toc:()=>p});var a=t(58168),o=t(98587),i=(t(96540),t(15680)),r=t(49595),s=["components"],c={id:"config_groups",title:"Config Groups"},l=void 0,d={unversionedId:"tutorials/structured_config/config_groups",id:"tutorials/structured_config/config_groups",title:"Config Groups",description:"Structured Configs can be used to implement config groups. Special care needs to be taken when specifying a",source:"@site/docs/tutorials/structured_config/3_config_groups.md",sourceDirName:"tutorials/structured_config",slug:"/tutorials/structured_config/config_groups",permalink:"/docs/tutorials/structured_config/config_groups",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/tutorials/structured_config/3_config_groups.md",tags:[],version:"current",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:3,frontMatter:{id:"config_groups",title:"Config Groups"},sidebar:"docs",previous:{title:"A hierarchical static configuration",permalink:"/docs/tutorials/structured_config/hierarchical_static_config"},next:{title:"Defaults List",permalink:"/docs/tutorials/structured_config/defaults"}},p=[{value:"Config inheritance",id:"config-inheritance",children:[],level:3},{value:"Missing fields",id:"missing-fields",children:[],level:3}],m={toc:p};function u(e){var n=e.components,t=(0,o.A)(e,s);return(0,i.mdx)("wrapper",(0,a.A)({},m,t,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)(r.C,{to:"examples/tutorials/structured_configs/3_config_groups/my_app.py",mdxType:"ExampleGithubLink"}),(0,i.mdx)("p",null,"Structured Configs can be used to implement config groups. Special care needs to be taken when specifying a\ndefault value for fields populated by a config group. We will look at why below."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Defining a config group for database" {16-17,22-23}',title:'"Defining',a:!0,config:!0,group:!0,for:!0,'database"':!0,"{16-17,22-23}":!0},'from dataclasses import dataclass\n\nimport hydra\nfrom hydra.core.config_store import ConfigStore\n\n@dataclass\nclass MySQLConfig:\n driver: str = "mysql"\n host: str = "localhost"\n port: int = 3306\n\n@dataclass\nclass PostGreSQLConfig:\n driver: str = "postgresql"\n host: str = "localhost"\n port: int = 5432\n timeout: int = 10\n\n@dataclass\nclass Config:\n # We will populate db using composition.\n db: Any\n\n# Create config group `db` with options \'mysql\' and \'postgreqsl\'\ncs = ConfigStore.instance()\ncs.store(name="config", node=Config)\ncs.store(group="db", name="mysql", node=MySQLConfig)\ncs.store(group="db", name="postgresql", node=PostGreSQLConfig)\n\n@hydra.main(version_base=None, config_name="config")\ndef my_app(cfg: Config) -> None:\n print(OmegaConf.to_yaml(cfg))\n\nif __name__ == "__main__":\n my_app()\n')),(0,i.mdx)("div",{className:"admonition admonition-caution alert alert--warning"},(0,i.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,i.mdx)("h5",{parentName:"div"},(0,i.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,i.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"16",height:"16",viewBox:"0 0 16 16"},(0,i.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"}))),"caution")),(0,i.mdx)("div",{parentName:"div",className:"admonition-content"},(0,i.mdx)("p",{parentName:"div"},"The ",(0,i.mdx)("em",{parentName:"p"},"Config")," class is ",(0,i.mdx)("strong",{parentName:"p"},"NOT")," the Defaults list. We will see the Defaults list in the next page."))),(0,i.mdx)("p",null,"You can select the database from the command line:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py +db=postgresql\ndb:\n driver: postgresql\n host: localhost\n password: drowssap\n port: 5432\n timeout: 10\n user: postgres_user\n")),(0,i.mdx)("p",null,"The ",(0,i.mdx)("inlineCode",{parentName:"p"},"+")," above is required because there is no default choice for the config group ",(0,i.mdx)("inlineCode",{parentName:"p"},"db"),".\nThe next page will reintroduce the Defaults List, eliminating the need for the ",(0,i.mdx)("inlineCode",{parentName:"p"},"+"),"."),(0,i.mdx)("h3",{id:"config-inheritance"},"Config inheritance"),(0,i.mdx)(r.C,{to:"examples/tutorials/structured_configs/3_config_groups/my_app_with_inheritance.py",mdxType:"ExampleGithubLink"}),(0,i.mdx)("p",null,"Standard Python inheritance can be used to get improved type safety, and to move common fields to the parent class."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Defining a config group for database using inheritance"',title:'"Defining',a:!0,config:!0,group:!0,for:!0,database:!0,using:!0,'inheritance"':!0},'from omegaconf import MISSING\n\n@dataclass\nclass DBConfig:\n host: str = "localhost"\n port: int = MISSING\n driver: str = MISSING\n\n@dataclass\nclass MySQLConfig(DBConfig):\n driver: str = "mysql"\n port: int = 3306\n\n@dataclass\nclass PostGreSQLConfig(DBConfig):\n driver: str = "postgresql"\n port: int = 5432\n timeout: int = 10\n\n@dataclass\nclass Config:\n # We can now annotate db as DBConfig which\n # improves both static and dynamic type safety.\n db: DBConfig\n')),(0,i.mdx)("h3",{id:"missing-fields"},"Missing fields"),(0,i.mdx)("p",null,"Assign ",(0,i.mdx)("em",{parentName:"p"},"MISSING")," to a field to indicates that it does not have a default value. This is equivalent to\nthe ",(0,i.mdx)("inlineCode",{parentName:"p"},"???")," literal we have seen in OmegaConf configs before."),(0,i.mdx)("p",null,"Omitting a default value is equivalent to assigning ",(0,i.mdx)("em",{parentName:"p"},"MISSING")," to it, although it is sometimes\nconvenient to be able to assign MISSING it to a field."),(0,i.mdx)("div",{className:"admonition admonition-caution alert alert--warning"},(0,i.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,i.mdx)("h5",{parentName:"div"},(0,i.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,i.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"16",height:"16",viewBox:"0 0 16 16"},(0,i.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"}))),"caution")),(0,i.mdx)("div",{parentName:"div",className:"admonition-content"},(0,i.mdx)("p",{parentName:"div"},"Do not confuse ",(0,i.mdx)("strong",{parentName:"p"},"omegaconf.MISSING")," with ",(0,i.mdx)("strong",{parentName:"p"},"dataclass.MISSING"),"."))))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/364e9131.51b669ba.js b/assets/js/364e9131.51b669ba.js deleted file mode 100644 index 7c5eb609f3..0000000000 --- a/assets/js/364e9131.51b669ba.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[8127],{15680:(e,t,r)=>{r.r(t),r.d(t,{MDXContext:()=>l,MDXProvider:()=>c,mdx:()=>v,useMDXComponents:()=>u,withMDXComponents:()=>p});var n=r(96540);function a(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(a[r]=e[r]);return a}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(a[r]=e[r])}return a}var l=n.createContext({}),p=function(e){return function(t){var r=u(t.components);return n.createElement(e,o({},t,{components:r}))}},u=function(e){var t=n.useContext(l),r=t;return e&&(r="function"==typeof e?e(t):s(s({},t),e)),r},c=function(e){var t=u(e.components);return n.createElement(l.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},f=n.forwardRef((function(e,t){var r=e.components,a=e.mdxType,o=e.originalType,i=e.parentName,l=d(e,["components","mdxType","originalType","parentName"]),p=u(r),c=a,f=p["".concat(i,".").concat(c)]||p[c]||m[c]||o;return r?n.createElement(f,s(s({ref:t},l),{},{components:r})):n.createElement(f,s({ref:t},l))}));function v(e,t){var r=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var o=r.length,i=new Array(o);i[0]=f;var s={};for(var d in t)hasOwnProperty.call(t,d)&&(s[d]=t[d]);s.originalType=e,s.mdxType="string"==typeof e?e:a,i[1]=s;for(var l=2;l{r.r(t),r.d(t,{contentTitle:()=>d,default:()=>c,frontMatter:()=>s,metadata:()=>l,toc:()=>p});var n=r(58168),a=r(98587),o=(r(96540),r(15680)),i=["components"],s={id:"defaults_list_override",title:"Defaults List Overrides"},d=void 0,l={unversionedId:"upgrades/1.0_to_1.1/defaults_list_override",id:"version-1.2/upgrades/1.0_to_1.1/defaults_list_override",title:"Defaults List Overrides",description:"Hydra versions prior to 1.1 supported overriding of Hydra config groups via the Defaults List in this manner:",source:"@site/versioned_docs/version-1.2/upgrades/1.0_to_1.1/defaults_list_override.md",sourceDirName:"upgrades/1.0_to_1.1",slug:"/upgrades/1.0_to_1.1/defaults_list_override",permalink:"/docs/1.2/upgrades/1.0_to_1.1/defaults_list_override",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/upgrades/1.0_to_1.1/defaults_list_override.md",tags:[],version:"1.2",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"defaults_list_override",title:"Defaults List Overrides"},sidebar:"docs",previous:{title:"Changes to default composition order",permalink:"/docs/1.2/upgrades/1.0_to_1.1/default_composition_order"},next:{title:"Defaults List interpolation",permalink:"/docs/1.2/upgrades/1.0_to_1.1/defaults_list_interpolation"}},p=[],u={toc:p};function c(e){var t=e.components,r=(0,a.A)(e,i);return(0,o.mdx)("wrapper",(0,n.A)({},u,r,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"Hydra versions prior to 1.1 supported overriding of Hydra config groups via the Defaults List in this manner:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{3}","{3}":!0},"defaults:\n - model: resnet50\n - hydra/launcher: submitit\n")),(0,o.mdx)("p",null,"As of Hydra 1.1, Config group overrides must be marked explicitly with the ",(0,o.mdx)("inlineCode",{parentName:"p"},"override")," keyword:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{3}","{3}":!0},"defaults:\n - model: resnet50\n - override hydra/launcher: submitit\n")),(0,o.mdx)("p",null,"The Defaults List is described ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.2/advanced/defaults_list"},"here"),"."),(0,o.mdx)("div",{className:"admonition admonition-warning alert alert--danger"},(0,o.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,o.mdx)("h5",{parentName:"div"},(0,o.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,o.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"12",height:"16",viewBox:"0 0 12 16"},(0,o.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M5.05.31c.81 2.17.41 3.38-.52 4.31C3.55 5.67 1.98 6.45.9 7.98c-1.45 2.05-1.7 6.53 3.53 7.7-2.2-1.16-2.67-4.52-.3-6.61-.61 2.03.53 3.33 1.94 2.86 1.39-.47 2.3.53 2.27 1.67-.02.78-.31 1.44-1.13 1.81 3.42-.59 4.78-3.42 4.78-5.56 0-2.84-2.53-3.22-1.25-5.61-1.52.13-2.03 1.13-1.89 2.75.09 1.08-1.02 1.8-1.86 1.33-.67-.41-.66-1.19-.06-1.78C8.18 5.31 8.68 2.45 5.05.32L5.03.3l.02.01z"}))),"warning")),(0,o.mdx)("div",{parentName:"div",className:"admonition-content"},(0,o.mdx)("p",{parentName:"div"},"Omitting the ",(0,o.mdx)("inlineCode",{parentName:"p"},"override")," keyword when overriding Hydra's config groups will result in an error in Hydra 1.2"))))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/364e9131.56cf4e3b.js b/assets/js/364e9131.56cf4e3b.js new file mode 100644 index 0000000000..7edcc66352 --- /dev/null +++ b/assets/js/364e9131.56cf4e3b.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[8127],{15680:(e,t,r)=>{r.r(t),r.d(t,{MDXContext:()=>l,MDXProvider:()=>c,mdx:()=>v,useMDXComponents:()=>u,withMDXComponents:()=>p});var n=r(96540);function a(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(a[r]=e[r]);return a}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(a[r]=e[r])}return a}var l=n.createContext({}),p=function(e){return function(t){var r=u(t.components);return n.createElement(e,o({},t,{components:r}))}},u=function(e){var t=n.useContext(l),r=t;return e&&(r="function"==typeof e?e(t):s(s({},t),e)),r},c=function(e){var t=u(e.components);return n.createElement(l.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},f=n.forwardRef((function(e,t){var r=e.components,a=e.mdxType,o=e.originalType,i=e.parentName,l=d(e,["components","mdxType","originalType","parentName"]),p=u(r),c=a,f=p["".concat(i,".").concat(c)]||p[c]||m[c]||o;return r?n.createElement(f,s(s({ref:t},l),{},{components:r})):n.createElement(f,s({ref:t},l))}));function v(e,t){var r=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var o=r.length,i=new Array(o);i[0]=f;var s={};for(var d in t)hasOwnProperty.call(t,d)&&(s[d]=t[d]);s.originalType=e,s.mdxType="string"==typeof e?e:a,i[1]=s;for(var l=2;l{r.r(t),r.d(t,{contentTitle:()=>d,default:()=>c,frontMatter:()=>s,metadata:()=>l,toc:()=>p});var n=r(58168),a=r(98587),o=(r(96540),r(15680)),i=["components"],s={id:"defaults_list_override",title:"Defaults List Overrides"},d=void 0,l={unversionedId:"upgrades/1.0_to_1.1/defaults_list_override",id:"version-1.2/upgrades/1.0_to_1.1/defaults_list_override",title:"Defaults List Overrides",description:"Hydra versions prior to 1.1 supported overriding of Hydra config groups via the Defaults List in this manner:",source:"@site/versioned_docs/version-1.2/upgrades/1.0_to_1.1/defaults_list_override.md",sourceDirName:"upgrades/1.0_to_1.1",slug:"/upgrades/1.0_to_1.1/defaults_list_override",permalink:"/docs/1.2/upgrades/1.0_to_1.1/defaults_list_override",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/upgrades/1.0_to_1.1/defaults_list_override.md",tags:[],version:"1.2",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"defaults_list_override",title:"Defaults List Overrides"},sidebar:"docs",previous:{title:"Changes to default composition order",permalink:"/docs/1.2/upgrades/1.0_to_1.1/default_composition_order"},next:{title:"Defaults List interpolation",permalink:"/docs/1.2/upgrades/1.0_to_1.1/defaults_list_interpolation"}},p=[],u={toc:p};function c(e){var t=e.components,r=(0,a.A)(e,i);return(0,o.mdx)("wrapper",(0,n.A)({},u,r,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"Hydra versions prior to 1.1 supported overriding of Hydra config groups via the Defaults List in this manner:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{3}","{3}":!0},"defaults:\n - model: resnet50\n - hydra/launcher: submitit\n")),(0,o.mdx)("p",null,"As of Hydra 1.1, Config group overrides must be marked explicitly with the ",(0,o.mdx)("inlineCode",{parentName:"p"},"override")," keyword:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{3}","{3}":!0},"defaults:\n - model: resnet50\n - override hydra/launcher: submitit\n")),(0,o.mdx)("p",null,"The Defaults List is described ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.2/advanced/defaults_list"},"here"),"."),(0,o.mdx)("div",{className:"admonition admonition-warning alert alert--danger"},(0,o.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,o.mdx)("h5",{parentName:"div"},(0,o.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,o.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"12",height:"16",viewBox:"0 0 12 16"},(0,o.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M5.05.31c.81 2.17.41 3.38-.52 4.31C3.55 5.67 1.98 6.45.9 7.98c-1.45 2.05-1.7 6.53 3.53 7.7-2.2-1.16-2.67-4.52-.3-6.61-.61 2.03.53 3.33 1.94 2.86 1.39-.47 2.3.53 2.27 1.67-.02.78-.31 1.44-1.13 1.81 3.42-.59 4.78-3.42 4.78-5.56 0-2.84-2.53-3.22-1.25-5.61-1.52.13-2.03 1.13-1.89 2.75.09 1.08-1.02 1.8-1.86 1.33-.67-.41-.66-1.19-.06-1.78C8.18 5.31 8.68 2.45 5.05.32L5.03.3l.02.01z"}))),"warning")),(0,o.mdx)("div",{parentName:"div",className:"admonition-content"},(0,o.mdx)("p",{parentName:"div"},"Omitting the ",(0,o.mdx)("inlineCode",{parentName:"p"},"override")," keyword when overriding Hydra's config groups will result in an error in Hydra 1.2"))))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/3721ffec.cc9ee28c.js b/assets/js/3721ffec.cc9ee28c.js new file mode 100644 index 0000000000..979a4b5840 --- /dev/null +++ b/assets/js/3721ffec.cc9ee28c.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[418],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>m,MDXProvider:()=>c,mdx:()=>g,useMDXComponents:()=>p,withMDXComponents:()=>s});var t=a(96540);function l(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function r(){return r=Object.assign||function(e){for(var n=1;n=0||(l[a]=e[a]);return l}(e,n);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(l[a]=e[a])}return l}var m=t.createContext({}),s=function(e){return function(n){var a=p(n.components);return t.createElement(e,r({},n,{components:a}))}},p=function(e){var n=t.useContext(m),a=n;return e&&(a="function"==typeof e?e(n):d(d({},n),e)),a},c=function(e){var n=p(e.components);return t.createElement(m.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return t.createElement(t.Fragment,{},n)}},f=t.forwardRef((function(e,n){var a=e.components,l=e.mdxType,r=e.originalType,i=e.parentName,m=o(e,["components","mdxType","originalType","parentName"]),s=p(a),c=l,f=s["".concat(i,".").concat(c)]||s[c]||u[c]||r;return a?t.createElement(f,d(d({ref:n},m),{},{components:a})):t.createElement(f,d({ref:n},m))}));function g(e,n){var a=arguments,l=n&&n.mdxType;if("string"==typeof e||l){var r=a.length,i=new Array(r);i[0]=f;var d={};for(var o in n)hasOwnProperty.call(n,o)&&(d[o]=n[o]);d.originalType=e,d.mdxType="string"==typeof e?e:l,i[1]=d;for(var m=2;m{a.r(n),a.d(n,{contentTitle:()=>o,default:()=>c,frontMatter:()=>d,metadata:()=>m,toc:()=>s});var t=a(58168),l=a(98587),r=(a(96540),a(15680)),i=["components"],d={id:"defaults_list",title:"The Defaults List"},o=void 0,m={unversionedId:"advanced/defaults_list",id:"version-1.2/advanced/defaults_list",title:"The Defaults List",description:"Introduction",source:"@site/versioned_docs/version-1.2/advanced/defaults_list.md",sourceDirName:"advanced",slug:"/advanced/defaults_list",permalink:"/docs/1.2/advanced/defaults_list",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/advanced/defaults_list.md",tags:[],version:"1.2",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"defaults_list",title:"The Defaults List"},sidebar:"docs",previous:{title:"Extended Override syntax",permalink:"/docs/1.2/advanced/override_grammar/extended"},next:{title:"Packages",permalink:"/docs/1.2/advanced/overriding_packages"}},s=[{value:"Introduction",id:"introduction",children:[],level:2},{value:"An example",id:"an-example",children:[],level:2},{value:"Overriding Config Group options",id:"overriding-config-group-options",children:[],level:2},{value:"Composition order",id:"composition-order",children:[],level:2},{value:"Interpolation in the Defaults List",id:"interpolation-in-the-defaults-list",children:[{value:"Restrictions:",id:"restrictions",children:[],level:4}],level:2},{value:"Debugging the Defaults List",id:"debugging-the-defaults-list",children:[],level:2},{value:"Related topics",id:"related-topics",children:[],level:2}],p={toc:s};function c(e){var n=e.components,a=(0,l.A)(e,i);return(0,r.mdx)("wrapper",(0,t.A)({},p,a,{components:n,mdxType:"MDXLayout"}),(0,r.mdx)("h2",{id:"introduction"},"Introduction"),(0,r.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,r.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,r.mdx)("h5",{parentName:"div"},(0,r.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,r.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,r.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,r.mdx)("div",{parentName:"div",className:"admonition-content"},(0,r.mdx)("p",{parentName:"div"},"Many of the features described in this page are new. Please report any issues."))),(0,r.mdx)("p",null,"The Defaults List is a list in an input config that instructs Hydra how to build the output config.\nEach input config can have a Defaults List as a top level element. The Defaults List itself\nis not a part of output config."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Defaults List YAML syntax"',title:'"Defaults',List:!0,YAML:!0,'syntax"':!0},"defaults:\n (- CONFIG|GROUP_DEFAULT)*\n\nCONFIG : (CONFIG_GROUP/)?CONFIG_NAME(@PACKAGE)?\nGROUP_DEFAULT : [optional|override]? CONFIG_GROUP(@PACKAGE)?: OPTION\nOPTION : CONFIG_NAME|CONFIG_NAMES|null\n")),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"CONFIG")," : A config to use when creating the output config. e.g. ",(0,r.mdx)("inlineCode",{parentName:"p"},"db/mysql"),", ",(0,r.mdx)("inlineCode",{parentName:"p"},"db/mysql@backup"),"."),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"GROUP_DEFAULT")," : An ",(0,r.mdx)("em",{parentName:"p"},"overridable")," config. e.g. ",(0,r.mdx)("inlineCode",{parentName:"p"},"db: mysql"),", ",(0,r.mdx)("inlineCode",{parentName:"p"},"db@backup: mysql"),"."),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("strong",{parentName:"li"},(0,r.mdx)("em",{parentName:"strong"},"override"))," : Overrides the option of a previously defined GROUP_DEFAULT."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("strong",{parentName:"li"},(0,r.mdx)("em",{parentName:"strong"},"optional"))," : By default, an OPTION that do not exist causes an error; optional suppresses the error. "),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("strong",{parentName:"li"},(0,r.mdx)("em",{parentName:"strong"},"null"))," : A place-holder for a future override. If it is not overridden the entry is ignored.")),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"CONFIG_NAME"),": The name of a config, without the file system extension. e.g. ",(0,r.mdx)("inlineCode",{parentName:"p"},"mysql")," and not ",(0,r.mdx)("inlineCode",{parentName:"p"},"mysql.yaml"),"."),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"CONFIG_NAMES")," : A list of config names. e.g. ",(0,r.mdx)("inlineCode",{parentName:"p"},"[mysql, sqlite]")),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"CONFIG_GROUP")," : A path to a set of configs.",(0,r.mdx)("br",{parentName:"p"}),"\n","The path is relative to the containing config.\nIt can be made absolute by prefixing it with a ",(0,r.mdx)("inlineCode",{parentName:"p"},"/"),".",(0,r.mdx)("br",{parentName:"p"}),"\n","The path separator is ",(0,r.mdx)("inlineCode",{parentName:"p"},"/")," regardless of the operating system."),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"OPTION"),": The currently selected ",(0,r.mdx)("em",{parentName:"p"},"CONFIG_NAME")," or ",(0,r.mdx)("em",{parentName:"p"},"CONFIG_NAMES")," from a ",(0,r.mdx)("em",{parentName:"p"},"CONFIG_GROUP"),". "),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"PACKAGE")," : Where to place the content of the config within the output config.\nIt is relative to the Package of the containing config by default. See ",(0,r.mdx)("a",{parentName:"p",href:"/docs/1.2/advanced/overriding_packages"},"Packages"),"."),(0,r.mdx)("h2",{id:"an-example"},"An example"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Config directory structure"',title:'"Config',directory:!0,'structure"':!0},"\u251c\u2500\u2500 server\n\u2502 \u251c\u2500\u2500 db\n\u2502 \u2502 \u251c\u2500\u2500 mysql.yaml\n\u2502 \u2502 \u2514\u2500\u2500 sqlite.yaml\n\u2502 \u2514\u2500\u2500 apache.yaml\n\u2514\u2500\u2500 config.yaml\n")),(0,r.mdx)("p",null,"Input configs:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - server/apache\n\ndebug: false\n\n\n\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/apache.yaml"',title:'"server/apache.yaml"'},"defaults:\n - db: mysql\n\nname: apache\n\n\n\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/db/mysql.yaml"',title:'"server/db/mysql.yaml"'},"name: mysql\n")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/db/sqlite.yaml"',title:'"server/db/sqlite.yaml"'},"name: sqlite\n")))),(0,r.mdx)("p",null,"Output config:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py"',title:'"$',python:!0,'my_app.py"':!0},"server:\n db:\n name: mysql\n name: apache\ndebug: false\n")),(0,r.mdx)("h2",{id:"overriding-config-group-options"},"Overriding Config Group options"),(0,r.mdx)("p",null,"A Config Group's option can be overridden using a new ",(0,r.mdx)("em",{parentName:"p"},"GROUP_DEFAULT")," with the ",(0,r.mdx)("strong",{parentName:"p"},(0,r.mdx)("em",{parentName:"strong"},"override"))," keyword.\nIf a Group Default is overridden more than once, the last one, in depth first order, wins."),(0,r.mdx)("p",null,"Extending the previous example:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {3}',title:'"config.yaml"',"{3}":!0},"defaults:\n - server/apache\n - override server/db: sqlite\n\ndebug: false\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py" {2,3}',title:'"$',python:!0,'my_app.py"':!0,"{2,3}":!0},"server:\n db:\n name: sqlite\n name: apache\ndebug: false\n")))),(0,r.mdx)("p",null,"A Config Group's option can also be overridden via the command line. e.g: "),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre"},"$ python my_app.py server/db=sqlite\n")),(0,r.mdx)("h2",{id:"composition-order"},"Composition order"),(0,r.mdx)("p",null,"The Defaults List is ordered:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"If multiple configs define the same value, the last one wins."),(0,r.mdx)("li",{parentName:"ul"},"If multiple configs contribute to the same dictionary, the result is the combined dictionary.")),(0,r.mdx)("p",null,"By default, the content of a config is overriding the content of configs in the defaults list."),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {5}',title:'"config.yaml"',"{5}":!0},"defaults:\n - db: mysql \n\ndb:\n host: backup\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Result: db.host from config" {3}',title:'"Result:',"db.host":!0,from:!0,'config"':!0,"{3}":!0},"db:\n driver: mysql # db/mysql.yaml\n host: backup # config.yaml\n port: 3306 # db/mysql.yaml\n\n")))),(0,r.mdx)("p",null,"The ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," entry determines the relative position of ",(0,r.mdx)("strong",{parentName:"p"},"this")," config in the Defaults List.\nIf it is not specified, it is added automatically as the last item."),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {2,6}',title:'"config.yaml"',"{2,6}":!0},"defaults:\n - _self_\n - db: mysql # Overrides this config \n\ndb:\n host: backup\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Result: All values from db/mysql" {3}',title:'"Result:',All:!0,values:!0,from:!0,'db/mysql"':!0,"{3}":!0},"db:\n driver: mysql # db/mysql.yaml\n host: localhost # db/mysql.yaml\n port: 3306 # db/mysql.yaml\n\n\n")))),(0,r.mdx)("p",null,"With ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," at the top of the Defaults List, the host field defined in ",(0,r.mdx)("em",{parentName:"p"},"config.yaml")," now precedes the host field defined\nin ",(0,r.mdx)("em",{parentName:"p"},"db/mysql.yaml"),", and as a result is overridden."),(0,r.mdx)("h2",{id:"interpolation-in-the-defaults-list"},"Interpolation in the Defaults List"),(0,r.mdx)("p",null,"Config Group Options can be selected using interpolation."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - server: apache\n - db: mysql\n - combination_specific_config: ${server}_${db} # apache_mysql\n")),(0,r.mdx)("p",null,"Interpolation keys can be config groups with any @package overrides.",(0,r.mdx)("br",{parentName:"p"}),"\n","For example: ",(0,r.mdx)("inlineCode",{parentName:"p"},"${db/engine}"),", ",(0,r.mdx)("inlineCode",{parentName:"p"},"${db@backup}")),(0,r.mdx)("p",null,"The selected option for ",(0,r.mdx)("em",{parentName:"p"},"combination_specific_config")," depends on the final selected options for ",(0,r.mdx)("em",{parentName:"p"},"db")," and ",(0,r.mdx)("em",{parentName:"p"},"server"),".",(0,r.mdx)("br",{parentName:"p"}),"\n","e.g., If ",(0,r.mdx)("em",{parentName:"p"},"db")," is overridden to ",(0,r.mdx)("em",{parentName:"p"},"sqlite"),", ",(0,r.mdx)("em",{parentName:"p"},"combination_specific_config")," will become ",(0,r.mdx)("em",{parentName:"p"},"apache_sqlite"),"."),(0,r.mdx)("h4",{id:"restrictions"},"Restrictions:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Interpolation keys in the Defaults List cannot reference values in the Final Config Object (it does not yet exist)."),(0,r.mdx)("li",{parentName:"ul"},"Defaults List interpolation keys are absolute (even in nested configs)."),(0,r.mdx)("li",{parentName:"ul"},"The subtree expanded by an Interpolated Config may not contain Default List overrides.")),(0,r.mdx)("p",null,"See ",(0,r.mdx)("a",{parentName:"p",href:"/docs/1.2/patterns/specializing_config"},"Patterns/Specializing Configs")," for more information."),(0,r.mdx)("h2",{id:"debugging-the-defaults-list"},"Debugging the Defaults List"),(0,r.mdx)("p",null,"Hydra's config composition process is as follows:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"The Defaults Tree is created."),(0,r.mdx)("li",{parentName:"ul"},"The Final Defaults List is created via a DFS walk of the Defaults Tree."),(0,r.mdx)("li",{parentName:"ul"},"The Output Config is composed from the entries in the Final Defaults List.")),(0,r.mdx)("p",null,"You can inspect these artifacts via command line flags:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"--info defaults-tree")," shows the Defaults Tree."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"--info defaults")," Shows the Final Defaults List."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"--cfg job|hydra|all")," Shows the Output Config.")),(0,r.mdx)("p",null,"Example outputs:"),(0,r.mdx)("details",null,(0,r.mdx)("summary",null,"python my_app.py ",(0,r.mdx)("b",null,"--info defaults-tree")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title=""',title:'""'},":\n hydra/config:\n hydra/hydra_logging: default\n hydra/job_logging: default\n hydra/launcher: basic\n hydra/sweeper: basic\n hydra/output: default\n hydra/help: default\n hydra/hydra_help: default\n _self_\n config:\n server/apache:\n server/db: mysql\n _self_\n _self_\n"))),(0,r.mdx)("details",null,(0,r.mdx)("summary",null,"python my_app.py ",(0,r.mdx)("b",null,"--info defaults")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-text"},"Defaults List\n*************\n| Config path | Package | _self_ | Parent | \n-------------------------------------------------------------------------------\n| hydra/hydra_logging/default | hydra.hydra_logging | False | hydra/config |\n| hydra/job_logging/default | hydra.job_logging | False | hydra/config |\n| hydra/launcher/basic | hydra.launcher | False | hydra/config |\n| hydra/sweeper/basic | hydra.sweeper | False | hydra/config |\n| hydra/output/default | hydra | False | hydra/config |\n| hydra/help/default | hydra.help | False | hydra/config |\n| hydra/hydra_help/default | hydra.hydra_help | False | hydra/config |\n| hydra/config | hydra | True | |\n| server/db/mysql | server.db | False | server/apache |\n| server/apache | server | True | config |\n| config | | True | |\n-------------------------------------------------------------------------------\n"))),(0,r.mdx)("details",null,(0,r.mdx)("summary",null,"python my_app.py ",(0,r.mdx)("b",null,"--cfg job")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml"},"server:\n db:\n name: mysql\n name: apache\ndebug: false\n"))),(0,r.mdx)("h2",{id:"related-topics"},"Related topics"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("a",{parentName:"li",href:"/docs/1.2/advanced/overriding_packages"},"Packages")),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("a",{parentName:"li",href:"/docs/1.2/patterns/extending_configs"},"Common Patterns/Extending Configs")),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("a",{parentName:"li",href:"/docs/1.2/patterns/configuring_experiments"},"Common Patterns/Configuring Experiments")),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("a",{parentName:"li",href:"/docs/1.2/patterns/select_multiple_configs_from_config_group"},"Selecting multiple configs from a Config Group"))))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/3721ffec.e3227b93.js b/assets/js/3721ffec.e3227b93.js deleted file mode 100644 index c6928a4eea..0000000000 --- a/assets/js/3721ffec.e3227b93.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[418],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>m,MDXProvider:()=>c,mdx:()=>g,useMDXComponents:()=>p,withMDXComponents:()=>s});var t=a(96540);function l(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function r(){return r=Object.assign||function(e){for(var n=1;n=0||(l[a]=e[a]);return l}(e,n);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(l[a]=e[a])}return l}var m=t.createContext({}),s=function(e){return function(n){var a=p(n.components);return t.createElement(e,r({},n,{components:a}))}},p=function(e){var n=t.useContext(m),a=n;return e&&(a="function"==typeof e?e(n):d(d({},n),e)),a},c=function(e){var n=p(e.components);return t.createElement(m.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return t.createElement(t.Fragment,{},n)}},f=t.forwardRef((function(e,n){var a=e.components,l=e.mdxType,r=e.originalType,i=e.parentName,m=o(e,["components","mdxType","originalType","parentName"]),s=p(a),c=l,f=s["".concat(i,".").concat(c)]||s[c]||u[c]||r;return a?t.createElement(f,d(d({ref:n},m),{},{components:a})):t.createElement(f,d({ref:n},m))}));function g(e,n){var a=arguments,l=n&&n.mdxType;if("string"==typeof e||l){var r=a.length,i=new Array(r);i[0]=f;var d={};for(var o in n)hasOwnProperty.call(n,o)&&(d[o]=n[o]);d.originalType=e,d.mdxType="string"==typeof e?e:l,i[1]=d;for(var m=2;m{a.r(n),a.d(n,{contentTitle:()=>o,default:()=>c,frontMatter:()=>d,metadata:()=>m,toc:()=>s});var t=a(58168),l=a(98587),r=(a(96540),a(15680)),i=["components"],d={id:"defaults_list",title:"The Defaults List"},o=void 0,m={unversionedId:"advanced/defaults_list",id:"version-1.2/advanced/defaults_list",title:"The Defaults List",description:"Introduction",source:"@site/versioned_docs/version-1.2/advanced/defaults_list.md",sourceDirName:"advanced",slug:"/advanced/defaults_list",permalink:"/docs/1.2/advanced/defaults_list",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/advanced/defaults_list.md",tags:[],version:"1.2",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"defaults_list",title:"The Defaults List"},sidebar:"docs",previous:{title:"Extended Override syntax",permalink:"/docs/1.2/advanced/override_grammar/extended"},next:{title:"Packages",permalink:"/docs/1.2/advanced/overriding_packages"}},s=[{value:"Introduction",id:"introduction",children:[],level:2},{value:"An example",id:"an-example",children:[],level:2},{value:"Overriding Config Group options",id:"overriding-config-group-options",children:[],level:2},{value:"Composition order",id:"composition-order",children:[],level:2},{value:"Interpolation in the Defaults List",id:"interpolation-in-the-defaults-list",children:[{value:"Restrictions:",id:"restrictions",children:[],level:4}],level:2},{value:"Debugging the Defaults List",id:"debugging-the-defaults-list",children:[],level:2},{value:"Related topics",id:"related-topics",children:[],level:2}],p={toc:s};function c(e){var n=e.components,a=(0,l.A)(e,i);return(0,r.mdx)("wrapper",(0,t.A)({},p,a,{components:n,mdxType:"MDXLayout"}),(0,r.mdx)("h2",{id:"introduction"},"Introduction"),(0,r.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,r.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,r.mdx)("h5",{parentName:"div"},(0,r.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,r.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,r.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,r.mdx)("div",{parentName:"div",className:"admonition-content"},(0,r.mdx)("p",{parentName:"div"},"Many of the features described in this page are new. Please report any issues."))),(0,r.mdx)("p",null,"The Defaults List is a list in an input config that instructs Hydra how to build the output config.\nEach input config can have a Defaults List as a top level element. The Defaults List itself\nis not a part of output config."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Defaults List YAML syntax"',title:'"Defaults',List:!0,YAML:!0,'syntax"':!0},"defaults:\n (- CONFIG|GROUP_DEFAULT)*\n\nCONFIG : (CONFIG_GROUP/)?CONFIG_NAME(@PACKAGE)?\nGROUP_DEFAULT : [optional|override]? CONFIG_GROUP(@PACKAGE)?: OPTION\nOPTION : CONFIG_NAME|CONFIG_NAMES|null\n")),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"CONFIG")," : A config to use when creating the output config. e.g. ",(0,r.mdx)("inlineCode",{parentName:"p"},"db/mysql"),", ",(0,r.mdx)("inlineCode",{parentName:"p"},"db/mysql@backup"),"."),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"GROUP_DEFAULT")," : An ",(0,r.mdx)("em",{parentName:"p"},"overridable")," config. e.g. ",(0,r.mdx)("inlineCode",{parentName:"p"},"db: mysql"),", ",(0,r.mdx)("inlineCode",{parentName:"p"},"db@backup: mysql"),"."),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("strong",{parentName:"li"},(0,r.mdx)("em",{parentName:"strong"},"override"))," : Overrides the option of a previously defined GROUP_DEFAULT."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("strong",{parentName:"li"},(0,r.mdx)("em",{parentName:"strong"},"optional"))," : By default, an OPTION that do not exist causes an error; optional suppresses the error. "),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("strong",{parentName:"li"},(0,r.mdx)("em",{parentName:"strong"},"null"))," : A place-holder for a future override. If it is not overridden the entry is ignored.")),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"CONFIG_NAME"),": The name of a config, without the file system extension. e.g. ",(0,r.mdx)("inlineCode",{parentName:"p"},"mysql")," and not ",(0,r.mdx)("inlineCode",{parentName:"p"},"mysql.yaml"),"."),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"CONFIG_NAMES")," : A list of config names. e.g. ",(0,r.mdx)("inlineCode",{parentName:"p"},"[mysql, sqlite]")),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"CONFIG_GROUP")," : A path to a set of configs.",(0,r.mdx)("br",{parentName:"p"}),"\n","The path is relative to the containing config.\nIt can be made absolute by prefixing it with a ",(0,r.mdx)("inlineCode",{parentName:"p"},"/"),".",(0,r.mdx)("br",{parentName:"p"}),"\n","The path separator is ",(0,r.mdx)("inlineCode",{parentName:"p"},"/")," regardless of the operating system."),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"OPTION"),": The currently selected ",(0,r.mdx)("em",{parentName:"p"},"CONFIG_NAME")," or ",(0,r.mdx)("em",{parentName:"p"},"CONFIG_NAMES")," from a ",(0,r.mdx)("em",{parentName:"p"},"CONFIG_GROUP"),". "),(0,r.mdx)("p",null,(0,r.mdx)("em",{parentName:"p"},"PACKAGE")," : Where to place the content of the config within the output config.\nIt is relative to the Package of the containing config by default. See ",(0,r.mdx)("a",{parentName:"p",href:"/docs/1.2/advanced/overriding_packages"},"Packages"),"."),(0,r.mdx)("h2",{id:"an-example"},"An example"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Config directory structure"',title:'"Config',directory:!0,'structure"':!0},"\u251c\u2500\u2500 server\n\u2502 \u251c\u2500\u2500 db\n\u2502 \u2502 \u251c\u2500\u2500 mysql.yaml\n\u2502 \u2502 \u2514\u2500\u2500 sqlite.yaml\n\u2502 \u2514\u2500\u2500 apache.yaml\n\u2514\u2500\u2500 config.yaml\n")),(0,r.mdx)("p",null,"Input configs:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - server/apache\n\ndebug: false\n\n\n\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/apache.yaml"',title:'"server/apache.yaml"'},"defaults:\n - db: mysql\n\nname: apache\n\n\n\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/db/mysql.yaml"',title:'"server/db/mysql.yaml"'},"name: mysql\n")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="server/db/sqlite.yaml"',title:'"server/db/sqlite.yaml"'},"name: sqlite\n")))),(0,r.mdx)("p",null,"Output config:"),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py"',title:'"$',python:!0,'my_app.py"':!0},"server:\n db:\n name: mysql\n name: apache\ndebug: false\n")),(0,r.mdx)("h2",{id:"overriding-config-group-options"},"Overriding Config Group options"),(0,r.mdx)("p",null,"A Config Group's option can be overridden using a new ",(0,r.mdx)("em",{parentName:"p"},"GROUP_DEFAULT")," with the ",(0,r.mdx)("strong",{parentName:"p"},(0,r.mdx)("em",{parentName:"strong"},"override"))," keyword.\nIf a Group Default is overridden more than once, the last one, in depth first order, wins."),(0,r.mdx)("p",null,"Extending the previous example:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {3}',title:'"config.yaml"',"{3}":!0},"defaults:\n - server/apache\n - override server/db: sqlite\n\ndebug: false\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py" {2,3}',title:'"$',python:!0,'my_app.py"':!0,"{2,3}":!0},"server:\n db:\n name: sqlite\n name: apache\ndebug: false\n")))),(0,r.mdx)("p",null,"A Config Group's option can also be overridden via the command line. e.g: "),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre"},"$ python my_app.py server/db=sqlite\n")),(0,r.mdx)("h2",{id:"composition-order"},"Composition order"),(0,r.mdx)("p",null,"The Defaults List is ordered:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"If multiple configs define the same value, the last one wins."),(0,r.mdx)("li",{parentName:"ul"},"If multiple configs contribute to the same dictionary, the result is the combined dictionary.")),(0,r.mdx)("p",null,"By default, the content of a config is overriding the content of configs in the defaults list."),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {5}',title:'"config.yaml"',"{5}":!0},"defaults:\n - db: mysql \n\ndb:\n host: backup\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Result: db.host from config" {3}',title:'"Result:',"db.host":!0,from:!0,'config"':!0,"{3}":!0},"db:\n driver: mysql # db/mysql.yaml\n host: backup # config.yaml\n port: 3306 # db/mysql.yaml\n\n")))),(0,r.mdx)("p",null,"The ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," entry determines the relative position of ",(0,r.mdx)("strong",{parentName:"p"},"this")," config in the Defaults List.\nIf it is not specified, it is added automatically as the last item."),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {2,6}',title:'"config.yaml"',"{2,6}":!0},"defaults:\n - _self_\n - db: mysql # Overrides this config \n\ndb:\n host: backup\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Result: All values from db/mysql" {3}',title:'"Result:',All:!0,values:!0,from:!0,'db/mysql"':!0,"{3}":!0},"db:\n driver: mysql # db/mysql.yaml\n host: localhost # db/mysql.yaml\n port: 3306 # db/mysql.yaml\n\n\n")))),(0,r.mdx)("p",null,"With ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," at the top of the Defaults List, the host field defined in ",(0,r.mdx)("em",{parentName:"p"},"config.yaml")," now precedes the host field defined\nin ",(0,r.mdx)("em",{parentName:"p"},"db/mysql.yaml"),", and as a result is overridden."),(0,r.mdx)("h2",{id:"interpolation-in-the-defaults-list"},"Interpolation in the Defaults List"),(0,r.mdx)("p",null,"Config Group Options can be selected using interpolation."),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - server: apache\n - db: mysql\n - combination_specific_config: ${server}_${db} # apache_mysql\n")),(0,r.mdx)("p",null,"Interpolation keys can be config groups with any @package overrides.",(0,r.mdx)("br",{parentName:"p"}),"\n","For example: ",(0,r.mdx)("inlineCode",{parentName:"p"},"${db/engine}"),", ",(0,r.mdx)("inlineCode",{parentName:"p"},"${db@backup}")),(0,r.mdx)("p",null,"The selected option for ",(0,r.mdx)("em",{parentName:"p"},"combination_specific_config")," depends on the final selected options for ",(0,r.mdx)("em",{parentName:"p"},"db")," and ",(0,r.mdx)("em",{parentName:"p"},"server"),".",(0,r.mdx)("br",{parentName:"p"}),"\n","e.g., If ",(0,r.mdx)("em",{parentName:"p"},"db")," is overridden to ",(0,r.mdx)("em",{parentName:"p"},"sqlite"),", ",(0,r.mdx)("em",{parentName:"p"},"combination_specific_config")," will become ",(0,r.mdx)("em",{parentName:"p"},"apache_sqlite"),"."),(0,r.mdx)("h4",{id:"restrictions"},"Restrictions:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"Interpolation keys in the Defaults List cannot reference values in the Final Config Object (it does not yet exist)."),(0,r.mdx)("li",{parentName:"ul"},"Defaults List interpolation keys are absolute (even in nested configs)."),(0,r.mdx)("li",{parentName:"ul"},"The subtree expanded by an Interpolated Config may not contain Default List overrides.")),(0,r.mdx)("p",null,"See ",(0,r.mdx)("a",{parentName:"p",href:"/docs/1.2/patterns/specializing_config"},"Patterns/Specializing Configs")," for more information."),(0,r.mdx)("h2",{id:"debugging-the-defaults-list"},"Debugging the Defaults List"),(0,r.mdx)("p",null,"Hydra's config composition process is as follows:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"The Defaults Tree is created."),(0,r.mdx)("li",{parentName:"ul"},"The Final Defaults List is created via a DFS walk of the Defaults Tree."),(0,r.mdx)("li",{parentName:"ul"},"The Output Config is composed from the entries in the Final Defaults List.")),(0,r.mdx)("p",null,"You can inspect these artifacts via command line flags:"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"--info defaults-tree")," shows the Defaults Tree."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"--info defaults")," Shows the Final Defaults List."),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("inlineCode",{parentName:"li"},"--cfg job|hydra|all")," Shows the Output Config.")),(0,r.mdx)("p",null,"Example outputs:"),(0,r.mdx)("details",null,(0,r.mdx)("summary",null,"python my_app.py ",(0,r.mdx)("b",null,"--info defaults-tree")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title=""',title:'""'},":\n hydra/config:\n hydra/hydra_logging: default\n hydra/job_logging: default\n hydra/launcher: basic\n hydra/sweeper: basic\n hydra/output: default\n hydra/help: default\n hydra/hydra_help: default\n _self_\n config:\n server/apache:\n server/db: mysql\n _self_\n _self_\n"))),(0,r.mdx)("details",null,(0,r.mdx)("summary",null,"python my_app.py ",(0,r.mdx)("b",null,"--info defaults")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-text"},"Defaults List\n*************\n| Config path | Package | _self_ | Parent | \n-------------------------------------------------------------------------------\n| hydra/hydra_logging/default | hydra.hydra_logging | False | hydra/config |\n| hydra/job_logging/default | hydra.job_logging | False | hydra/config |\n| hydra/launcher/basic | hydra.launcher | False | hydra/config |\n| hydra/sweeper/basic | hydra.sweeper | False | hydra/config |\n| hydra/output/default | hydra | False | hydra/config |\n| hydra/help/default | hydra.help | False | hydra/config |\n| hydra/hydra_help/default | hydra.hydra_help | False | hydra/config |\n| hydra/config | hydra | True | |\n| server/db/mysql | server.db | False | server/apache |\n| server/apache | server | True | config |\n| config | | True | |\n-------------------------------------------------------------------------------\n"))),(0,r.mdx)("details",null,(0,r.mdx)("summary",null,"python my_app.py ",(0,r.mdx)("b",null,"--cfg job")),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml"},"server:\n db:\n name: mysql\n name: apache\ndebug: false\n"))),(0,r.mdx)("h2",{id:"related-topics"},"Related topics"),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("a",{parentName:"li",href:"/docs/1.2/advanced/overriding_packages"},"Packages")),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("a",{parentName:"li",href:"/docs/1.2/patterns/extending_configs"},"Common Patterns/Extending Configs")),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("a",{parentName:"li",href:"/docs/1.2/patterns/configuring_experiments"},"Common Patterns/Configuring Experiments")),(0,r.mdx)("li",{parentName:"ul"},(0,r.mdx)("a",{parentName:"li",href:"/docs/1.2/patterns/select_multiple_configs_from_config_group"},"Selecting multiple configs from a Config Group"))))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/37b83927.09334b12.js b/assets/js/37b83927.09334b12.js deleted file mode 100644 index c6f060790b..0000000000 --- a/assets/js/37b83927.09334b12.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[6262],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>s,MDXProvider:()=>u,mdx:()=>h,useMDXComponents:()=>m,withMDXComponents:()=>c});var a=n(96540);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var s=a.createContext({}),c=function(e){return function(t){var n=m(t.components);return a.createElement(e,o({},t,{components:n}))}},m=function(e){var t=a.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},u=function(e){var t=m(e.components);return a.createElement(s.Provider,{value:t},e.children)},p={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},f=a.forwardRef((function(e,t){var n=e.components,i=e.mdxType,o=e.originalType,r=e.parentName,s=d(e,["components","mdxType","originalType","parentName"]),c=m(n),u=i,f=c["".concat(r,".").concat(u)]||c[u]||p[u]||o;return n?a.createElement(f,l(l({ref:t},s),{},{components:n})):a.createElement(f,l({ref:t},s))}));function h(e,t){var n=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var o=n.length,r=new Array(o);r[0]=f;var l={};for(var d in t)hasOwnProperty.call(t,d)&&(l[d]=t[d]);l.originalType=e,l.mdxType="string"==typeof e?e:i,r[1]=l;for(var s=2;s{n.r(t),n.d(t,{contentTitle:()=>d,default:()=>u,frontMatter:()=>l,metadata:()=>s,toc:()=>c});var a=n(58168),i=n(98587),o=(n(96540),n(15680)),r=["components"],l={id:"specializing_config",title:"Specializing configuration",sidebar_label:"Specializing configuration"},d=void 0,s={unversionedId:"patterns/specializing_config",id:"version-0.11/patterns/specializing_config",title:"Specializing configuration",description:"In some cases the desired configuration should depend on other configuration choices.",source:"@site/versioned_docs/version-0.11/patterns/specializing_config.md",sourceDirName:"patterns",slug:"/patterns/specializing_config",permalink:"/docs/0.11/patterns/specializing_config",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-0.11/patterns/specializing_config.md",tags:[],version:"0.11",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"specializing_config",title:"Specializing configuration",sidebar_label:"Specializing configuration"},sidebar:"version-0.11/docs",previous:{title:"Creating objects",permalink:"/docs/0.11/patterns/objects"},next:{title:"Introduction",permalink:"/docs/0.11/configure_hydra/intro"}},c=[{value:"initial config.yaml",id:"initial-configyaml",children:[],level:3},{value:"modified config.yaml",id:"modified-configyaml",children:[{value:"dataset_model",id:"dataset_model",children:[],level:4},{value:"${defaults.0.dataset}_${defaults.1.model}",id:"defaults0dataset_defaults1model",children:[],level:4},{value:"optional: true",id:"optional-true",children:[],level:4}],level:3},{value:"dataset_model/cifar10_alexnet.yaml",id:"dataset_modelcifar10_alexnetyaml",children:[],level:3}],m={toc:c};function u(e){var t=e.components,n=(0,i.A)(e,r);return(0,o.mdx)("wrapper",(0,a.A)({},m,n,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"In some cases the desired configuration should depend on other configuration choices.\nFor example, You may want to use only 5 layers in your Alexnet model if the dataset of choice is cifar10, and the default 7 otherwise."),(0,o.mdx)("p",null,"We can start with a config that looks like this:"),(0,o.mdx)("h3",{id:"initial-configyaml"},"initial config.yaml"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - dataset: imagenet\n - model: alexnet\n")),(0,o.mdx)("p",null,"We want to specialize the config based on the choice of the selected dataset and model:\nFurthermore, we only want to do it for cifar10 and alexnet and not for 3 other combinations."),(0,o.mdx)("p",null,"OmegaConf supports value interpolation, we can construct a value that would - at runtime - be a function of other values.\nThe idea is that we can add another element to the defaults list that would load a file name that depends on those two values:"),(0,o.mdx)("h3",{id:"modified-configyaml"},"modified config.yaml"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - dataset: imagenet\n - model: alexnet\n - dataset_model: ${defaults.0.dataset}_${defaults.1.model}\n optional: true\n")),(0,o.mdx)("p",null,"Let's break this down:"),(0,o.mdx)("h4",{id:"dataset_model"},"dataset_model"),(0,o.mdx)("p",null,"The key ",(0,o.mdx)("inlineCode",{parentName:"p"},"dataset_model")," is an arbitrary directory, it can be anything unique that makes sense, including nested directory like ",(0,o.mdx)("inlineCode",{parentName:"p"},"dataset/model"),"."),(0,o.mdx)("h4",{id:"defaults0dataset_defaults1model"},"${defaults.0.dataset}_${defaults.1.model}"),(0,o.mdx)("p",null,"the value ",(0,o.mdx)("inlineCode",{parentName:"p"},"${defaults.0.dataset}_${defaults.1.model}")," is using OmegaConf's ",(0,o.mdx)("a",{parentName:"p",href:"https://omegaconf.readthedocs.io/en/latest/usage.html#variable-interpolation"},"variable interpolation"),".\nAt runtime, that value would resolve to ",(0,o.mdx)("em",{parentName:"p"},"imagenet_alexnet"),", or ",(0,o.mdx)("em",{parentName:"p"},"cifar_resnet")," - depending on the values of defaults.dataset and defaults.model.\nThis a bit clunky because defaults contains a list (I hope to improve this in the future)"),(0,o.mdx)("h4",{id:"optional-true"},"optional: true"),(0,o.mdx)("p",null,"By default, Hydra would fail with an error if a config specified in the defaults does not exist.\nin this case we only want to specialize cifar10 + alexnet, not all 4 combinations.\nindication optional: true here tells Hydra to just continue if it can't find this file."),(0,o.mdx)("p",null,"When specializing config, you usually want to only specify what's different, and not the whole thing.\nWe want the model for alexnet, when trained on cifar - to have 5 layers."),(0,o.mdx)("h3",{id:"dataset_modelcifar10_alexnetyaml"},"dataset_model/cifar10_alexnet.yaml"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"model:\n num_layers: 5\n")),(0,o.mdx)("p",null,"Let's check. Running with the default uses imagenet, so we don't get the specialized version of:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python example.py \ndataset:\n name: imagenet\n path: /datasets/imagenet\nmodel:\n num_layers: 7\n type: alexnet\n")),(0,o.mdx)("p",null,"Running with cifar10 dataset, we do get 5 for num_layers:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python example.py dataset=cifar10\ndataset:\n name: cifar10\n path: /datasets/cifar10\nmodel:\n num_layers: 5\n type: alexnet\n")))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/37b83927.cfcb166f.js b/assets/js/37b83927.cfcb166f.js new file mode 100644 index 0000000000..3f1cd5b0ba --- /dev/null +++ b/assets/js/37b83927.cfcb166f.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[6262],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>s,MDXProvider:()=>u,mdx:()=>h,useMDXComponents:()=>m,withMDXComponents:()=>c});var a=n(96540);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var s=a.createContext({}),c=function(e){return function(t){var n=m(t.components);return a.createElement(e,o({},t,{components:n}))}},m=function(e){var t=a.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},u=function(e){var t=m(e.components);return a.createElement(s.Provider,{value:t},e.children)},p={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},f=a.forwardRef((function(e,t){var n=e.components,i=e.mdxType,o=e.originalType,r=e.parentName,s=d(e,["components","mdxType","originalType","parentName"]),c=m(n),u=i,f=c["".concat(r,".").concat(u)]||c[u]||p[u]||o;return n?a.createElement(f,l(l({ref:t},s),{},{components:n})):a.createElement(f,l({ref:t},s))}));function h(e,t){var n=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var o=n.length,r=new Array(o);r[0]=f;var l={};for(var d in t)hasOwnProperty.call(t,d)&&(l[d]=t[d]);l.originalType=e,l.mdxType="string"==typeof e?e:i,r[1]=l;for(var s=2;s{n.r(t),n.d(t,{contentTitle:()=>d,default:()=>u,frontMatter:()=>l,metadata:()=>s,toc:()=>c});var a=n(58168),i=n(98587),o=(n(96540),n(15680)),r=["components"],l={id:"specializing_config",title:"Specializing configuration",sidebar_label:"Specializing configuration"},d=void 0,s={unversionedId:"patterns/specializing_config",id:"version-0.11/patterns/specializing_config",title:"Specializing configuration",description:"In some cases the desired configuration should depend on other configuration choices.",source:"@site/versioned_docs/version-0.11/patterns/specializing_config.md",sourceDirName:"patterns",slug:"/patterns/specializing_config",permalink:"/docs/0.11/patterns/specializing_config",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-0.11/patterns/specializing_config.md",tags:[],version:"0.11",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"specializing_config",title:"Specializing configuration",sidebar_label:"Specializing configuration"},sidebar:"version-0.11/docs",previous:{title:"Creating objects",permalink:"/docs/0.11/patterns/objects"},next:{title:"Introduction",permalink:"/docs/0.11/configure_hydra/intro"}},c=[{value:"initial config.yaml",id:"initial-configyaml",children:[],level:3},{value:"modified config.yaml",id:"modified-configyaml",children:[{value:"dataset_model",id:"dataset_model",children:[],level:4},{value:"${defaults.0.dataset}_${defaults.1.model}",id:"defaults0dataset_defaults1model",children:[],level:4},{value:"optional: true",id:"optional-true",children:[],level:4}],level:3},{value:"dataset_model/cifar10_alexnet.yaml",id:"dataset_modelcifar10_alexnetyaml",children:[],level:3}],m={toc:c};function u(e){var t=e.components,n=(0,i.A)(e,r);return(0,o.mdx)("wrapper",(0,a.A)({},m,n,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"In some cases the desired configuration should depend on other configuration choices.\nFor example, You may want to use only 5 layers in your Alexnet model if the dataset of choice is cifar10, and the default 7 otherwise."),(0,o.mdx)("p",null,"We can start with a config that looks like this:"),(0,o.mdx)("h3",{id:"initial-configyaml"},"initial config.yaml"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - dataset: imagenet\n - model: alexnet\n")),(0,o.mdx)("p",null,"We want to specialize the config based on the choice of the selected dataset and model:\nFurthermore, we only want to do it for cifar10 and alexnet and not for 3 other combinations."),(0,o.mdx)("p",null,"OmegaConf supports value interpolation, we can construct a value that would - at runtime - be a function of other values.\nThe idea is that we can add another element to the defaults list that would load a file name that depends on those two values:"),(0,o.mdx)("h3",{id:"modified-configyaml"},"modified config.yaml"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - dataset: imagenet\n - model: alexnet\n - dataset_model: ${defaults.0.dataset}_${defaults.1.model}\n optional: true\n")),(0,o.mdx)("p",null,"Let's break this down:"),(0,o.mdx)("h4",{id:"dataset_model"},"dataset_model"),(0,o.mdx)("p",null,"The key ",(0,o.mdx)("inlineCode",{parentName:"p"},"dataset_model")," is an arbitrary directory, it can be anything unique that makes sense, including nested directory like ",(0,o.mdx)("inlineCode",{parentName:"p"},"dataset/model"),"."),(0,o.mdx)("h4",{id:"defaults0dataset_defaults1model"},"${defaults.0.dataset}_${defaults.1.model}"),(0,o.mdx)("p",null,"the value ",(0,o.mdx)("inlineCode",{parentName:"p"},"${defaults.0.dataset}_${defaults.1.model}")," is using OmegaConf's ",(0,o.mdx)("a",{parentName:"p",href:"https://omegaconf.readthedocs.io/en/latest/usage.html#variable-interpolation"},"variable interpolation"),".\nAt runtime, that value would resolve to ",(0,o.mdx)("em",{parentName:"p"},"imagenet_alexnet"),", or ",(0,o.mdx)("em",{parentName:"p"},"cifar_resnet")," - depending on the values of defaults.dataset and defaults.model.\nThis a bit clunky because defaults contains a list (I hope to improve this in the future)"),(0,o.mdx)("h4",{id:"optional-true"},"optional: true"),(0,o.mdx)("p",null,"By default, Hydra would fail with an error if a config specified in the defaults does not exist.\nin this case we only want to specialize cifar10 + alexnet, not all 4 combinations.\nindication optional: true here tells Hydra to just continue if it can't find this file."),(0,o.mdx)("p",null,"When specializing config, you usually want to only specify what's different, and not the whole thing.\nWe want the model for alexnet, when trained on cifar - to have 5 layers."),(0,o.mdx)("h3",{id:"dataset_modelcifar10_alexnetyaml"},"dataset_model/cifar10_alexnet.yaml"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"model:\n num_layers: 5\n")),(0,o.mdx)("p",null,"Let's check. Running with the default uses imagenet, so we don't get the specialized version of:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python example.py \ndataset:\n name: imagenet\n path: /datasets/imagenet\nmodel:\n num_layers: 7\n type: alexnet\n")),(0,o.mdx)("p",null,"Running with cifar10 dataset, we do get 5 for num_layers:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python example.py dataset=cifar10\ndataset:\n name: cifar10\n path: /datasets/cifar10\nmodel:\n num_layers: 5\n type: alexnet\n")))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/38d99aff.afa76178.js b/assets/js/38d99aff.afa76178.js new file mode 100644 index 0000000000..faead9ce3e --- /dev/null +++ b/assets/js/38d99aff.afa76178.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[8885],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>d,MDXProvider:()=>p,mdx:()=>f,useMDXComponents:()=>c,withMDXComponents:()=>m});var r=t(96540);function a(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function o(){return o=Object.assign||function(e){for(var n=1;n=0||(a[t]=e[t]);return a}(e,n);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(a[t]=e[t])}return a}var d=r.createContext({}),m=function(e){return function(n){var t=c(n.components);return r.createElement(e,o({},n,{components:t}))}},c=function(e){var n=r.useContext(d),t=n;return e&&(t="function"==typeof e?e(n):s(s({},n),e)),t},p=function(e){var n=c(e.components);return r.createElement(d.Provider,{value:n},e.children)},g={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},u=r.forwardRef((function(e,n){var t=e.components,a=e.mdxType,o=e.originalType,i=e.parentName,d=l(e,["components","mdxType","originalType","parentName"]),m=c(t),p=a,u=m["".concat(i,".").concat(p)]||m[p]||g[p]||o;return t?r.createElement(u,s(s({ref:n},d),{},{components:t})):r.createElement(u,s({ref:n},d))}));function f(e,n){var t=arguments,a=n&&n.mdxType;if("string"==typeof e||a){var o=t.length,i=new Array(o);i[0]=u;var s={};for(var l in n)hasOwnProperty.call(n,l)&&(s[l]=n[l]);s.originalType=e,s.mdxType="string"==typeof e?e:a,i[1]=s;for(var d=2;d{t.d(n,{A:()=>l,C:()=>d});var r=t(58168),a=t(96540),o=t(75489),i=t(44586),s=t(74098);function l(e){return a.createElement(o.default,(0,r.A)({},e,{to:(n=e.to,l=(0,s.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==l?void 0:l.name)?t:"current"]+n),target:"_blank"}));var n,t,l}function d(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return a.createElement(l,e,a.createElement("span",null,"\xa0"),a.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},88214:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>d,default:()=>g,frontMatter:()=>l,metadata:()=>m,toc:()=>c});var r=t(58168),a=t(98587),o=(t(96540),t(15680)),i=t(49595),s=["components"],l={id:"extending_configs",title:"Extending Configs"},d=void 0,m={unversionedId:"patterns/extending_configs",id:"version-1.1/patterns/extending_configs",title:"Extending Configs",description:"A common pattern is to extend an existing config, overriding and/or adding new config values to it.",source:"@site/versioned_docs/version-1.1/patterns/extending_configs.md",sourceDirName:"patterns",slug:"/patterns/extending_configs",permalink:"/docs/1.1/patterns/extending_configs",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/patterns/extending_configs.md",tags:[],version:"1.1",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"extending_configs",title:"Extending Configs"},sidebar:"version-1.1/docs",previous:{title:"Structured Config schema",permalink:"/docs/1.1/tutorials/structured_config/schema"},next:{title:"Configuring Experiments",permalink:"/docs/1.1/patterns/configuring_experiments"}},c=[{value:"Extending a config from the same config group:",id:"extending-a-config-from-the-same-config-group",children:[],level:4},{value:"Extending a config from another config group:",id:"extending-a-config-from-another-config-group",children:[],level:4}],p={toc:c};function g(e){var n=e.components,t=(0,a.A)(e,s);return(0,o.mdx)("wrapper",(0,r.A)({},p,t,{components:n,mdxType:"MDXLayout"}),(0,o.mdx)(i.C,{text:"Example application",to:"examples/patterns/extending_configs",mdxType:"ExampleGithubLink"}),(0,o.mdx)("p",null,"A common pattern is to extend an existing config, overriding and/or adding new config values to it.\nThe extension is done by including the base configuration, and then overriding the chosen values in the current config."),(0,o.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,o.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,o.mdx)("h5",{parentName:"div"},(0,o.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,o.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,o.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"info")),(0,o.mdx)("div",{parentName:"div",className:"admonition-content"},(0,o.mdx)("p",{parentName:"div"},"This page assumes that you are familiar with the contents of ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.1/advanced/defaults_list"},"The Defaults List"),"."))),(0,o.mdx)("h4",{id:"extending-a-config-from-the-same-config-group"},"Extending a config from the same config group:"),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--4"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - db: mysql \n\n\n\n\n\n"))),(0,o.mdx)("div",{className:"col col--4"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml" {2}',title:'"db/mysql.yaml"',"{2}":!0},"defaults:\n - base_mysql\n\nuser: omry\npassword: secret\nport: 3307\nencoding: utf8\n"))),(0,o.mdx)("div",{className:"col col--4"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/base_mysql.yaml"',title:'"db/base_mysql.yaml"'},"host: localhost\nport: 3306\nuser: ???\npassword: ???\n\n\n\n")))),(0,o.mdx)("p",null,"Output:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py"',title:'"$',python:!0,'my_app.py"':!0},"db:\n host: localhost # from db/base_mysql\n port: 3307 # overriden by db/mysql.yaml \n user: omry # populated by db/mysql.yaml\n password: secret # populated by db/mysql.yaml\n encoding: utf8 # added by db/mysql.yaml\n")),(0,o.mdx)("h4",{id:"extending-a-config-from-another-config-group"},"Extending a config from another config group:"),(0,o.mdx)("p",null,"To extend a config from a different config group, include it using an absolute path (/), and override\nthe package to ",(0,o.mdx)("em",{parentName:"p"},"_","here","_"),". (",(0,o.mdx)("em",{parentName:"p"},"_","here","_")," is described in ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.1/advanced/overriding_packages#default-list-package-keywords"},"Packages"),")"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml" {2}',title:'"db/mysql.yaml"',"{2}":!0},"defaults:\n - /db_schema/base_mysql@_here_\n")),(0,o.mdx)("p",null,"It is otherwise identical to extending a config within the same config group."))}g.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/38d99aff.cb272b1a.js b/assets/js/38d99aff.cb272b1a.js deleted file mode 100644 index 717af64100..0000000000 --- a/assets/js/38d99aff.cb272b1a.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[8885],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>d,MDXProvider:()=>p,mdx:()=>f,useMDXComponents:()=>c,withMDXComponents:()=>m});var r=t(96540);function a(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function o(){return o=Object.assign||function(e){for(var n=1;n=0||(a[t]=e[t]);return a}(e,n);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(a[t]=e[t])}return a}var d=r.createContext({}),m=function(e){return function(n){var t=c(n.components);return r.createElement(e,o({},n,{components:t}))}},c=function(e){var n=r.useContext(d),t=n;return e&&(t="function"==typeof e?e(n):s(s({},n),e)),t},p=function(e){var n=c(e.components);return r.createElement(d.Provider,{value:n},e.children)},g={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},u=r.forwardRef((function(e,n){var t=e.components,a=e.mdxType,o=e.originalType,i=e.parentName,d=l(e,["components","mdxType","originalType","parentName"]),m=c(t),p=a,u=m["".concat(i,".").concat(p)]||m[p]||g[p]||o;return t?r.createElement(u,s(s({ref:n},d),{},{components:t})):r.createElement(u,s({ref:n},d))}));function f(e,n){var t=arguments,a=n&&n.mdxType;if("string"==typeof e||a){var o=t.length,i=new Array(o);i[0]=u;var s={};for(var l in n)hasOwnProperty.call(n,l)&&(s[l]=n[l]);s.originalType=e,s.mdxType="string"==typeof e?e:a,i[1]=s;for(var d=2;d{t.d(n,{A:()=>l,C:()=>d});var r=t(58168),a=t(96540),o=t(75489),i=t(44586),s=t(74098);function l(e){return a.createElement(o.default,(0,r.A)({},e,{to:(n=e.to,l=(0,s.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==l?void 0:l.name)?t:"current"]+n),target:"_blank"}));var n,t,l}function d(e){var n,t=null!=(n=e.text)?n:"Example (Click Here)";return a.createElement(l,e,a.createElement("span",null,"\xa0"),a.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},88214:(e,n,t)=>{t.r(n),t.d(n,{contentTitle:()=>d,default:()=>g,frontMatter:()=>l,metadata:()=>m,toc:()=>c});var r=t(58168),a=t(98587),o=(t(96540),t(15680)),i=t(49595),s=["components"],l={id:"extending_configs",title:"Extending Configs"},d=void 0,m={unversionedId:"patterns/extending_configs",id:"version-1.1/patterns/extending_configs",title:"Extending Configs",description:"A common pattern is to extend an existing config, overriding and/or adding new config values to it.",source:"@site/versioned_docs/version-1.1/patterns/extending_configs.md",sourceDirName:"patterns",slug:"/patterns/extending_configs",permalink:"/docs/1.1/patterns/extending_configs",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/patterns/extending_configs.md",tags:[],version:"1.1",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"extending_configs",title:"Extending Configs"},sidebar:"version-1.1/docs",previous:{title:"Structured Config schema",permalink:"/docs/1.1/tutorials/structured_config/schema"},next:{title:"Configuring Experiments",permalink:"/docs/1.1/patterns/configuring_experiments"}},c=[{value:"Extending a config from the same config group:",id:"extending-a-config-from-the-same-config-group",children:[],level:4},{value:"Extending a config from another config group:",id:"extending-a-config-from-another-config-group",children:[],level:4}],p={toc:c};function g(e){var n=e.components,t=(0,a.A)(e,s);return(0,o.mdx)("wrapper",(0,r.A)({},p,t,{components:n,mdxType:"MDXLayout"}),(0,o.mdx)(i.C,{text:"Example application",to:"examples/patterns/extending_configs",mdxType:"ExampleGithubLink"}),(0,o.mdx)("p",null,"A common pattern is to extend an existing config, overriding and/or adding new config values to it.\nThe extension is done by including the base configuration, and then overriding the chosen values in the current config."),(0,o.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,o.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,o.mdx)("h5",{parentName:"div"},(0,o.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,o.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,o.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"info")),(0,o.mdx)("div",{parentName:"div",className:"admonition-content"},(0,o.mdx)("p",{parentName:"div"},"This page assumes that you are familiar with the contents of ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.1/advanced/defaults_list"},"The Defaults List"),"."))),(0,o.mdx)("h4",{id:"extending-a-config-from-the-same-config-group"},"Extending a config from the same config group:"),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--4"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - db: mysql \n\n\n\n\n\n"))),(0,o.mdx)("div",{className:"col col--4"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml" {2}',title:'"db/mysql.yaml"',"{2}":!0},"defaults:\n - base_mysql\n\nuser: omry\npassword: secret\nport: 3307\nencoding: utf8\n"))),(0,o.mdx)("div",{className:"col col--4"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/base_mysql.yaml"',title:'"db/base_mysql.yaml"'},"host: localhost\nport: 3306\nuser: ???\npassword: ???\n\n\n\n")))),(0,o.mdx)("p",null,"Output:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python my_app.py"',title:'"$',python:!0,'my_app.py"':!0},"db:\n host: localhost # from db/base_mysql\n port: 3307 # overriden by db/mysql.yaml \n user: omry # populated by db/mysql.yaml\n password: secret # populated by db/mysql.yaml\n encoding: utf8 # added by db/mysql.yaml\n")),(0,o.mdx)("h4",{id:"extending-a-config-from-another-config-group"},"Extending a config from another config group:"),(0,o.mdx)("p",null,"To extend a config from a different config group, include it using an absolute path (/), and override\nthe package to ",(0,o.mdx)("em",{parentName:"p"},"_","here","_"),". (",(0,o.mdx)("em",{parentName:"p"},"_","here","_")," is described in ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.1/advanced/overriding_packages#default-list-package-keywords"},"Packages"),")"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml" {2}',title:'"db/mysql.yaml"',"{2}":!0},"defaults:\n - /db_schema/base_mysql@_here_\n")),(0,o.mdx)("p",null,"It is otherwise identical to extending a config within the same config group."))}g.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/38f8d538.86e5fcbb.js b/assets/js/38f8d538.86e5fcbb.js new file mode 100644 index 0000000000..c172eb04a9 --- /dev/null +++ b/assets/js/38f8d538.86e5fcbb.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[1808],{15680:(e,n,r)=>{r.r(n),r.d(n,{MDXContext:()=>s,MDXProvider:()=>c,mdx:()=>g,useMDXComponents:()=>u,withMDXComponents:()=>d});var t=r(96540);function a(e,n,r){return n in e?Object.defineProperty(e,n,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[n]=r,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(a[r]=e[r]);return a}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(a[r]=e[r])}return a}var s=t.createContext({}),d=function(e){return function(n){var r=u(n.components);return t.createElement(e,i({},n,{components:r}))}},u=function(e){var n=t.useContext(s),r=n;return e&&(r="function"==typeof e?e(n):o(o({},n),e)),r},c=function(e){var n=u(e.components);return t.createElement(s.Provider,{value:n},e.children)},m={inlineCode:"code",wrapper:function(e){var n=e.children;return t.createElement(t.Fragment,{},n)}},h=t.forwardRef((function(e,n){var r=e.components,a=e.mdxType,i=e.originalType,l=e.parentName,s=p(e,["components","mdxType","originalType","parentName"]),d=u(r),c=a,h=d["".concat(l,".").concat(c)]||d[c]||m[c]||i;return r?t.createElement(h,o(o({ref:n},s),{},{components:r})):t.createElement(h,o({ref:n},s))}));function g(e,n){var r=arguments,a=n&&n.mdxType;if("string"==typeof e||a){var i=r.length,l=new Array(i);l[0]=h;var o={};for(var p in n)hasOwnProperty.call(n,p)&&(o[p]=n[p]);o.originalType=e,o.mdxType="string"==typeof e?e:a,l[1]=o;for(var s=2;s{r.d(n,{A:()=>p,C:()=>s});var t=r(58168),a=r(96540),i=r(75489),l=r(44586),o=r(74098);function p(e){return a.createElement(i.default,(0,t.A)({},e,{to:(n=e.to,p=(0,o.useActiveVersion)(),(0,l.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(r=null==p?void 0:p.name)?r:"current"]+n),target:"_blank"}));var n,r,p}function s(e){var n,r=null!=(n=e.text)?n:"Example (Click Here)";return a.createElement(p,e,a.createElement("span",null,"\xa0"),a.createElement("img",{src:"https://img.shields.io/badge/-"+r+"-informational",alt:"Example (Click Here)"}))}},25589:(e,n,r)=>{r.r(n),r.d(n,{contentTitle:()=>s,default:()=>m,frontMatter:()=>p,metadata:()=>d,toc:()=>u});var t=r(58168),a=r(98587),i=(r(96540),r(15680)),l=r(49595),o=["components"],p={id:"rq_launcher",title:"RQ Launcher plugin",sidebar_label:"RQ Launcher plugin"},s=void 0,d={unversionedId:"plugins/rq_launcher",id:"version-1.1/plugins/rq_launcher",title:"RQ Launcher plugin",description:"PyPI",source:"@site/versioned_docs/version-1.1/plugins/rq_launcher.md",sourceDirName:"plugins",slug:"/plugins/rq_launcher",permalink:"/docs/1.1/plugins/rq_launcher",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/plugins/rq_launcher.md",tags:[],version:"1.1",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"rq_launcher",title:"RQ Launcher plugin",sidebar_label:"RQ Launcher plugin"},sidebar:"version-1.1/docs",previous:{title:"Ray Launcher plugin",permalink:"/docs/1.1/plugins/ray_launcher"},next:{title:"Submitit Launcher plugin",permalink:"/docs/1.1/plugins/submitit_launcher"}},u=[{value:"Installation",id:"installation",children:[],level:3},{value:"Usage",id:"usage",children:[],level:3}],c={toc:u};function m(e){var n=e.components,r=(0,a.A)(e,o);return(0,i.mdx)("wrapper",(0,t.A)({},c,r,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,(0,i.mdx)("a",{parentName:"p",href:"https://pypi.org/project/hydra-rq-launcher/"},(0,i.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/v/hydra-rq-launcher",alt:"PyPI"})),"\n",(0,i.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/l/hydra-rq-launcher",alt:"PyPI - License"}),"\n",(0,i.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/pyversions/hydra-rq-launcher",alt:"PyPI - Python Version"}),"\n",(0,i.mdx)("a",{parentName:"p",href:"https://pypistats.org/packages/hydra-rq-launcher"},(0,i.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/dm/hydra-rq-launcher.svg",alt:"PyPI - Downloads"})),(0,i.mdx)(l.C,{text:"Example application",to:"plugins/hydra_rq_launcher/examples",mdxType:"ExampleGithubLink"}),(0,i.mdx)(l.C,{text:"Plugin source",to:"plugins/hydra_rq_launcher",mdxType:"ExampleGithubLink"})),(0,i.mdx)("p",null,"The RQ Launcher plugin provides a launcher for distributed execution and job queuing based on ",(0,i.mdx)("a",{parentName:"p",href:"https://python-rq.org"},"Redis Queue (RQ)"),"."),(0,i.mdx)("p",null,"RQ launcher allows parallelizing across multiple nodes and scheduling jobs in queues. Usage of this plugin requires a ",(0,i.mdx)("a",{parentName:"p",href:"https://redis.io/topics/quickstart"},"Redis server"),". When parallelisation on a single node is intended, the Joblib launcher may be preferable, since it works without a database."),(0,i.mdx)("h3",{id:"installation"},"Installation"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"pip install hydra-rq-launcher --upgrade\n")),(0,i.mdx)("p",null,"Usage of this plugin requires a ",(0,i.mdx)("a",{parentName:"p",href:"https://redis.io/topics/quickstart"},"Redis server"),"."),(0,i.mdx)("p",null,"Note that RQ does ",(0,i.mdx)("a",{parentName:"p",href:"https://python-rq.org/docs/#limitations"},"not support Windows"),"."),(0,i.mdx)("h3",{id:"usage"},"Usage"),(0,i.mdx)("p",null,"Once installed, add ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra/launcher=rq")," to your command line. Alternatively, override ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra/launcher")," in your config:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - override hydra/launcher: rq\n")),(0,i.mdx)("p",null,"The default configuration is as follows:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python your_app.py hydra/launcher=rq --cfg hydra -p hydra.launcher"',title:'"$',python:!0,"your_app.py":!0,"hydra/launcher":"rq","--cfg":!0,hydra:!0,"-p":!0,'hydra.launcher"':!0},"# @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")),(0,i.mdx)("p",null,"Further descriptions on the variables can be found in the plugin config file, defined ",(0,i.mdx)(l.A,{to:"plugins/hydra_rq_launcher/hydra_plugins/hydra_rq_launcher/config.py",mdxType:"GithubLink"},"here"),". There are several standard approaches for configuring plugins. Check ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.1/patterns/configuring_plugins"},"this page")," for more information."),(0,i.mdx)("p",null,"The plugin is using environment variables to store Redis connection information. The environment variables ",(0,i.mdx)("inlineCode",{parentName:"p"},"REDIS_HOST"),", ",(0,i.mdx)("inlineCode",{parentName:"p"},"REDIS_PORT"),", ",(0,i.mdx)("inlineCode",{parentName:"p"},"REDIS_DB"),", and ",(0,i.mdx)("inlineCode",{parentName:"p"},"REDIS_PASSWORD"),", are used for the host address, port, database, and password of the server, respectively. Support for Redis SSL connections is controlled through ",(0,i.mdx)("inlineCode",{parentName:"p"},"REDIS_SSL")," and ",(0,i.mdx)("inlineCode",{parentName:"p"},"REDIS_SSL_CA_CERTS"),"; see ",(0,i.mdx)("a",{parentName:"p",href:"https://github.com/andymccurdy/redis-py#ssl-connections"},"redis-py")," documentation."),(0,i.mdx)("p",null,"For example, they might be set as follows when using ",(0,i.mdx)("inlineCode",{parentName:"p"},"bash")," or ",(0,i.mdx)("inlineCode",{parentName:"p"},"zsh")," as a shell:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},'export REDIS_HOST="localhost"\nexport REDIS_PORT="6379"\nexport REDIS_DB="0"\nexport REDIS_PASSWORD=""\n')),(0,i.mdx)("p",null,"Enable SSL by setting the relevant environment variables. e.g:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"export REDIS_SSL=true\nexport REDIS_SSL_CA_CERTS=/etc/ssl/certs/ca-certificates.crt\n")),(0,i.mdx)("p",null,"Assuming configured environment variables, workers connecting to the Redis server can be launched using:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"rq worker --url redis://:$REDIS_PASSWORD@$REDIS_HOST:$REDIS_PORT/$REDIS_DB\n")),(0,i.mdx)("p",null,"An ",(0,i.mdx)(l.A,{to:"plugins/hydra_rq_launcher/example",mdxType:"GithubLink"},"example application")," using this launcher is provided in the plugin repository."),(0,i.mdx)("p",null,"Starting the app with ",(0,i.mdx)("inlineCode",{parentName:"p"},"python my_app.py --multirun task=1,2,3,4,5")," will enqueue five jobs to be processed by worker instances:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text"},"$ 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] #1 : task=1\n[HYDRA] Enqueued 00c6a32d-e5a4-432c-a0f3-b9d4ef0dd585\n[HYDRA] #2 : task=2\n[HYDRA] Enqueued 63b90f27-0711-4c95-8f63-70164fd850df\n[HYDRA] #3 : task=3\n[HYDRA] Enqueued b1d49825-8b28-4516-90ca-8106477e1eb1\n[HYDRA] #4 : task=4\n[HYDRA] Enqueued ed96bdaa-087d-4c7f-9ecb-56daf948d5e2\n[HYDRA] #5 : task=5\n[HYDRA] Finished enqueuing\n[HYDRA] Polling job statuses every 1.0 sec\n")),(0,i.mdx)("p",null,"Note that any dependencies need to be installed in the Python environment used to run the RQ worker. For serialization of jobs ",(0,i.mdx)("a",{parentName:"p",href:"https://github.com/cloudpickle/cloudpickle"},(0,i.mdx)("inlineCode",{parentName:"a"},"cloudpickle"))," is used."),(0,i.mdx)("p",null,"The ",(0,i.mdx)("a",{parentName:"p",href:"https://python-rq.org/"},"RQ documentation")," holds further information on ",(0,i.mdx)("a",{parentName:"p",href:"http://python-rq.org/docs/monitoring/"},"job monitoring"),", which can be done via console or ",(0,i.mdx)("a",{parentName:"p",href:"https://github.com/nvie/rq-dashboard"},"web interfaces"),", and provides ",(0,i.mdx)("a",{parentName:"p",href:"https://python-rq.org/patterns/"},"patterns")," for worker and exception handling."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/38f8d538.f25c8c5e.js b/assets/js/38f8d538.f25c8c5e.js deleted file mode 100644 index fa2c872a77..0000000000 --- a/assets/js/38f8d538.f25c8c5e.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[1808],{15680:(e,n,r)=>{r.r(n),r.d(n,{MDXContext:()=>s,MDXProvider:()=>c,mdx:()=>g,useMDXComponents:()=>u,withMDXComponents:()=>d});var t=r(96540);function a(e,n,r){return n in e?Object.defineProperty(e,n,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[n]=r,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(a[r]=e[r]);return a}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(a[r]=e[r])}return a}var s=t.createContext({}),d=function(e){return function(n){var r=u(n.components);return t.createElement(e,i({},n,{components:r}))}},u=function(e){var n=t.useContext(s),r=n;return e&&(r="function"==typeof e?e(n):o(o({},n),e)),r},c=function(e){var n=u(e.components);return t.createElement(s.Provider,{value:n},e.children)},m={inlineCode:"code",wrapper:function(e){var n=e.children;return t.createElement(t.Fragment,{},n)}},h=t.forwardRef((function(e,n){var r=e.components,a=e.mdxType,i=e.originalType,l=e.parentName,s=p(e,["components","mdxType","originalType","parentName"]),d=u(r),c=a,h=d["".concat(l,".").concat(c)]||d[c]||m[c]||i;return r?t.createElement(h,o(o({ref:n},s),{},{components:r})):t.createElement(h,o({ref:n},s))}));function g(e,n){var r=arguments,a=n&&n.mdxType;if("string"==typeof e||a){var i=r.length,l=new Array(i);l[0]=h;var o={};for(var p in n)hasOwnProperty.call(n,p)&&(o[p]=n[p]);o.originalType=e,o.mdxType="string"==typeof e?e:a,l[1]=o;for(var s=2;s{r.d(n,{A:()=>p,C:()=>s});var t=r(58168),a=r(96540),i=r(75489),l=r(44586),o=r(74098);function p(e){return a.createElement(i.default,(0,t.A)({},e,{to:(n=e.to,p=(0,o.useActiveVersion)(),(0,l.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(r=null==p?void 0:p.name)?r:"current"]+n),target:"_blank"}));var n,r,p}function s(e){var n,r=null!=(n=e.text)?n:"Example (Click Here)";return a.createElement(p,e,a.createElement("span",null,"\xa0"),a.createElement("img",{src:"https://img.shields.io/badge/-"+r+"-informational",alt:"Example (Click Here)"}))}},25589:(e,n,r)=>{r.r(n),r.d(n,{contentTitle:()=>s,default:()=>m,frontMatter:()=>p,metadata:()=>d,toc:()=>u});var t=r(58168),a=r(98587),i=(r(96540),r(15680)),l=r(49595),o=["components"],p={id:"rq_launcher",title:"RQ Launcher plugin",sidebar_label:"RQ Launcher plugin"},s=void 0,d={unversionedId:"plugins/rq_launcher",id:"version-1.1/plugins/rq_launcher",title:"RQ Launcher plugin",description:"PyPI",source:"@site/versioned_docs/version-1.1/plugins/rq_launcher.md",sourceDirName:"plugins",slug:"/plugins/rq_launcher",permalink:"/docs/1.1/plugins/rq_launcher",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/plugins/rq_launcher.md",tags:[],version:"1.1",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"rq_launcher",title:"RQ Launcher plugin",sidebar_label:"RQ Launcher plugin"},sidebar:"version-1.1/docs",previous:{title:"Ray Launcher plugin",permalink:"/docs/1.1/plugins/ray_launcher"},next:{title:"Submitit Launcher plugin",permalink:"/docs/1.1/plugins/submitit_launcher"}},u=[{value:"Installation",id:"installation",children:[],level:3},{value:"Usage",id:"usage",children:[],level:3}],c={toc:u};function m(e){var n=e.components,r=(0,a.A)(e,o);return(0,i.mdx)("wrapper",(0,t.A)({},c,r,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,(0,i.mdx)("a",{parentName:"p",href:"https://pypi.org/project/hydra-rq-launcher/"},(0,i.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/v/hydra-rq-launcher",alt:"PyPI"})),"\n",(0,i.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/l/hydra-rq-launcher",alt:"PyPI - License"}),"\n",(0,i.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/pyversions/hydra-rq-launcher",alt:"PyPI - Python Version"}),"\n",(0,i.mdx)("a",{parentName:"p",href:"https://pypistats.org/packages/hydra-rq-launcher"},(0,i.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/dm/hydra-rq-launcher.svg",alt:"PyPI - Downloads"})),(0,i.mdx)(l.C,{text:"Example application",to:"plugins/hydra_rq_launcher/examples",mdxType:"ExampleGithubLink"}),(0,i.mdx)(l.C,{text:"Plugin source",to:"plugins/hydra_rq_launcher",mdxType:"ExampleGithubLink"})),(0,i.mdx)("p",null,"The RQ Launcher plugin provides a launcher for distributed execution and job queuing based on ",(0,i.mdx)("a",{parentName:"p",href:"https://python-rq.org"},"Redis Queue (RQ)"),"."),(0,i.mdx)("p",null,"RQ launcher allows parallelizing across multiple nodes and scheduling jobs in queues. Usage of this plugin requires a ",(0,i.mdx)("a",{parentName:"p",href:"https://redis.io/topics/quickstart"},"Redis server"),". When parallelisation on a single node is intended, the Joblib launcher may be preferable, since it works without a database."),(0,i.mdx)("h3",{id:"installation"},"Installation"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"pip install hydra-rq-launcher --upgrade\n")),(0,i.mdx)("p",null,"Usage of this plugin requires a ",(0,i.mdx)("a",{parentName:"p",href:"https://redis.io/topics/quickstart"},"Redis server"),"."),(0,i.mdx)("p",null,"Note that RQ does ",(0,i.mdx)("a",{parentName:"p",href:"https://python-rq.org/docs/#limitations"},"not support Windows"),"."),(0,i.mdx)("h3",{id:"usage"},"Usage"),(0,i.mdx)("p",null,"Once installed, add ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra/launcher=rq")," to your command line. Alternatively, override ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra/launcher")," in your config:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - override hydra/launcher: rq\n")),(0,i.mdx)("p",null,"The default configuration is as follows:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python your_app.py hydra/launcher=rq --cfg hydra -p hydra.launcher"',title:'"$',python:!0,"your_app.py":!0,"hydra/launcher":"rq","--cfg":!0,hydra:!0,"-p":!0,'hydra.launcher"':!0},"# @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")),(0,i.mdx)("p",null,"Further descriptions on the variables can be found in the plugin config file, defined ",(0,i.mdx)(l.A,{to:"plugins/hydra_rq_launcher/hydra_plugins/hydra_rq_launcher/config.py",mdxType:"GithubLink"},"here"),". There are several standard approaches for configuring plugins. Check ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.1/patterns/configuring_plugins"},"this page")," for more information."),(0,i.mdx)("p",null,"The plugin is using environment variables to store Redis connection information. The environment variables ",(0,i.mdx)("inlineCode",{parentName:"p"},"REDIS_HOST"),", ",(0,i.mdx)("inlineCode",{parentName:"p"},"REDIS_PORT"),", ",(0,i.mdx)("inlineCode",{parentName:"p"},"REDIS_DB"),", and ",(0,i.mdx)("inlineCode",{parentName:"p"},"REDIS_PASSWORD"),", are used for the host address, port, database, and password of the server, respectively. Support for Redis SSL connections is controlled through ",(0,i.mdx)("inlineCode",{parentName:"p"},"REDIS_SSL")," and ",(0,i.mdx)("inlineCode",{parentName:"p"},"REDIS_SSL_CA_CERTS"),"; see ",(0,i.mdx)("a",{parentName:"p",href:"https://github.com/andymccurdy/redis-py#ssl-connections"},"redis-py")," documentation."),(0,i.mdx)("p",null,"For example, they might be set as follows when using ",(0,i.mdx)("inlineCode",{parentName:"p"},"bash")," or ",(0,i.mdx)("inlineCode",{parentName:"p"},"zsh")," as a shell:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},'export REDIS_HOST="localhost"\nexport REDIS_PORT="6379"\nexport REDIS_DB="0"\nexport REDIS_PASSWORD=""\n')),(0,i.mdx)("p",null,"Enable SSL by setting the relevant environment variables. e.g:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"export REDIS_SSL=true\nexport REDIS_SSL_CA_CERTS=/etc/ssl/certs/ca-certificates.crt\n")),(0,i.mdx)("p",null,"Assuming configured environment variables, workers connecting to the Redis server can be launched using:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"rq worker --url redis://:$REDIS_PASSWORD@$REDIS_HOST:$REDIS_PORT/$REDIS_DB\n")),(0,i.mdx)("p",null,"An ",(0,i.mdx)(l.A,{to:"plugins/hydra_rq_launcher/example",mdxType:"GithubLink"},"example application")," using this launcher is provided in the plugin repository."),(0,i.mdx)("p",null,"Starting the app with ",(0,i.mdx)("inlineCode",{parentName:"p"},"python my_app.py --multirun task=1,2,3,4,5")," will enqueue five jobs to be processed by worker instances:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text"},"$ 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] #1 : task=1\n[HYDRA] Enqueued 00c6a32d-e5a4-432c-a0f3-b9d4ef0dd585\n[HYDRA] #2 : task=2\n[HYDRA] Enqueued 63b90f27-0711-4c95-8f63-70164fd850df\n[HYDRA] #3 : task=3\n[HYDRA] Enqueued b1d49825-8b28-4516-90ca-8106477e1eb1\n[HYDRA] #4 : task=4\n[HYDRA] Enqueued ed96bdaa-087d-4c7f-9ecb-56daf948d5e2\n[HYDRA] #5 : task=5\n[HYDRA] Finished enqueuing\n[HYDRA] Polling job statuses every 1.0 sec\n")),(0,i.mdx)("p",null,"Note that any dependencies need to be installed in the Python environment used to run the RQ worker. For serialization of jobs ",(0,i.mdx)("a",{parentName:"p",href:"https://github.com/cloudpickle/cloudpickle"},(0,i.mdx)("inlineCode",{parentName:"a"},"cloudpickle"))," is used."),(0,i.mdx)("p",null,"The ",(0,i.mdx)("a",{parentName:"p",href:"https://python-rq.org/"},"RQ documentation")," holds further information on ",(0,i.mdx)("a",{parentName:"p",href:"http://python-rq.org/docs/monitoring/"},"job monitoring"),", which can be done via console or ",(0,i.mdx)("a",{parentName:"p",href:"https://github.com/nvie/rq-dashboard"},"web interfaces"),", and provides ",(0,i.mdx)("a",{parentName:"p",href:"https://python-rq.org/patterns/"},"patterns")," for worker and exception handling."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/3955c41d.05dd9f6c.js b/assets/js/3955c41d.05dd9f6c.js new file mode 100644 index 0000000000..878d9997d4 --- /dev/null +++ b/assets/js/3955c41d.05dd9f6c.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[7603],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>m,MDXProvider:()=>u,mdx:()=>y,useMDXComponents:()=>s,withMDXComponents:()=>p});var t=a(96540);function r(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(r[a]=e[a]);return r}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(r[a]=e[a])}return r}var m=t.createContext({}),p=function(e){return function(n){var a=s(n.components);return t.createElement(e,i({},n,{components:a}))}},s=function(e){var n=t.useContext(m),a=n;return e&&(a="function"==typeof e?e(n):l(l({},n),e)),a},u=function(e){var n=s(e.components);return t.createElement(m.Provider,{value:n},e.children)},c={inlineCode:"code",wrapper:function(e){var n=e.children;return t.createElement(t.Fragment,{},n)}},h=t.forwardRef((function(e,n){var a=e.components,r=e.mdxType,i=e.originalType,o=e.parentName,m=d(e,["components","mdxType","originalType","parentName"]),p=s(a),u=r,h=p["".concat(o,".").concat(u)]||p[u]||c[u]||i;return a?t.createElement(h,l(l({ref:n},m),{},{components:a})):t.createElement(h,l({ref:n},m))}));function y(e,n){var a=arguments,r=n&&n.mdxType;if("string"==typeof e||r){var i=a.length,o=new Array(i);o[0]=h;var l={};for(var d in n)hasOwnProperty.call(n,d)&&(l[d]=n[d]);l.originalType=e,l.mdxType="string"==typeof e?e:r,o[1]=l;for(var m=2;m{a.d(n,{A:()=>d,C:()=>m});var t=a(58168),r=a(96540),i=a(75489),o=a(44586),l=a(74098);function d(e){return r.createElement(i.default,(0,t.A)({},e,{to:(n=e.to,d=(0,l.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(a=null==d?void 0:d.name)?a:"current"]+n),target:"_blank"}));var n,a,d}function m(e){var n,a=null!=(n=e.text)?n:"Example (Click Here)";return r.createElement(d,e,r.createElement("span",null,"\xa0"),r.createElement("img",{src:"https://img.shields.io/badge/-"+a+"-informational",alt:"Example (Click Here)"}))}},58574:(e,n,a)=>{a.r(n),a.d(n,{contentTitle:()=>m,default:()=>c,frontMatter:()=>d,metadata:()=>p,toc:()=>s});var t=a(58168),r=a(98587),i=(a(96540),a(15680)),o=a(49595),l=["components"],d={id:"multi-run",title:"Multi-run",sidebar_label:"Multi-run"},m=void 0,p={unversionedId:"tutorials/basic/running_your_app/multi-run",id:"tutorials/basic/running_your_app/multi-run",title:"Multi-run",description:"Sometimes you want to run the same application with multiple different configurations.",source:"@site/docs/tutorials/basic/running_your_app/2_multirun.md",sourceDirName:"tutorials/basic/running_your_app",slug:"/tutorials/basic/running_your_app/multi-run",permalink:"/docs/tutorials/basic/running_your_app/multi-run",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/tutorials/basic/running_your_app/2_multirun.md",tags:[],version:"current",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:2,frontMatter:{id:"multi-run",title:"Multi-run",sidebar_label:"Multi-run"},sidebar:"docs",previous:{title:"Putting it all together",permalink:"/docs/tutorials/basic/your_first_app/composition"},next:{title:"Output/Working directory",permalink:"/docs/tutorials/basic/running_your_app/working_directory"}},s=[{value:"Configure hydra.mode (new in Hydra 1.2)",id:"configure-hydramode-new-in-hydra-12",children:[],level:3},{value:"--multirun (-m) from the command-line",id:"--multirun--m-from-the-command-line",children:[],level:3},{value:"Sweeping via hydra.sweeper.params",id:"sweeping-via-hydrasweeperparams",children:[],level:3},{value:"Additional sweep types",id:"additional-sweep-types",children:[],level:3},{value:"Sweeper",id:"sweeper",children:[],level:3},{value:"Launcher",id:"launcher",children:[],level:3}],u={toc:s};function c(e){var n=e.components,a=(0,r.A)(e,l);return(0,i.mdx)("wrapper",(0,t.A)({},u,a,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Sometimes you want to run the same application with multiple different configurations.",(0,i.mdx)("br",{parentName:"p"}),"\n","E.g. running a performance test on each of the databases with each of the schemas."),(0,i.mdx)("p",null,"You can multirun a Hydra application via either commandline or configuration:"),(0,i.mdx)("h3",{id:"configure-hydramode-new-in-hydra-12"},"Configure ",(0,i.mdx)("inlineCode",{parentName:"h3"},"hydra.mode")," (new in Hydra 1.2)"),(0,i.mdx)("p",null,"You can configure ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.mode")," in any supported way. The legal values are ",(0,i.mdx)("inlineCode",{parentName:"p"},"RUN")," and ",(0,i.mdx)("inlineCode",{parentName:"p"},"MULTIRUN"),".\nThe following shows how to override from the command-line and sweep over all combinations of the dbs and schemas.\nSetting ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.mode=MULTIRUN")," in your input config would make your application multi-run by default."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="$ python my_app.py hydra.mode=MULTIRUN db=mysql,postgresql schema=warehouse,support,school"',title:'"$',python:!0,"my_app.py":!0,"hydra.mode":"MULTIRUN",db:"mysql,postgresql",schema:'warehouse,support,school"'},"[2021-01-20 17:25:03,317][HYDRA] Launching 6 jobs locally\n[2021-01-20 17:25:03,318][HYDRA] #0 : db=mysql schema=warehouse\n[2021-01-20 17:25:03,458][HYDRA] #1 : db=mysql schema=support\n[2021-01-20 17:25:03,602][HYDRA] #2 : db=mysql schema=school\n[2021-01-20 17:25:03,755][HYDRA] #3 : db=postgresql schema=warehouse\n[2021-01-20 17:25:03,895][HYDRA] #4 : db=postgresql schema=support\n[2021-01-20 17:25:04,040][HYDRA] #5 : db=postgresql schema=school\n")),(0,i.mdx)("p",null,"The printed configurations have been omitted for brevity."),(0,i.mdx)("h3",{id:"--multirun--m-from-the-command-line"},(0,i.mdx)("inlineCode",{parentName:"h3"},"--multirun (-m)")," from the command-line"),(0,i.mdx)("p",null,"You can achieve the above from command-line as well:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"python my_app.py --multirun db=mysql,postgresql schema=warehouse,support,school\n")),(0,i.mdx)("p",null,"or "),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"python my_app.py -m db=mysql,postgresql schema=warehouse,support,school\n")),(0,i.mdx)("p",null,"You can access ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.mode")," at runtime to determine whether the application is in RUN or MULTIRUN mode. Check ",(0,i.mdx)("a",{parentName:"p",href:"/docs/configure_hydra/intro"},"here"),"\non how to access Hydra config at run time."),(0,i.mdx)("p",null,"If conflicts arise (e.g., ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.mode=RUN")," and the application was run with ",(0,i.mdx)("inlineCode",{parentName:"p"},"--multirun"),"), Hydra will determine the value of ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.mode"),"\nat run time. The following table shows what runtime ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.mode")," value you'd get with different input configs and commandline combinations."),(0,i.mdx)("table",null,(0,i.mdx)("thead",{parentName:"table"},(0,i.mdx)("tr",{parentName:"thead"},(0,i.mdx)("th",{parentName:"tr",align:null}),(0,i.mdx)("th",{parentName:"tr",align:null},"No multirun commandline flag"),(0,i.mdx)("th",{parentName:"tr",align:null},"--multirun ( -m)"))),(0,i.mdx)("tbody",{parentName:"table"},(0,i.mdx)("tr",{parentName:"tbody"},(0,i.mdx)("td",{parentName:"tr",align:null},"hydra.mode=RUN"),(0,i.mdx)("td",{parentName:"tr",align:null},"RunMode.RUN"),(0,i.mdx)("td",{parentName:"tr",align:null},"RunMode.MULTIRUN (with UserWarning)")),(0,i.mdx)("tr",{parentName:"tbody"},(0,i.mdx)("td",{parentName:"tr",align:null},"hydra.mode=MULTIRUN"),(0,i.mdx)("td",{parentName:"tr",align:null},"RunMode.MULTIRUN"),(0,i.mdx)("td",{parentName:"tr",align:null},"RunMode.MULTIRUN")),(0,i.mdx)("tr",{parentName:"tbody"},(0,i.mdx)("td",{parentName:"tr",align:null},"hydra.mode=None (default)"),(0,i.mdx)("td",{parentName:"tr",align:null},"RunMode.RUN"),(0,i.mdx)("td",{parentName:"tr",align:null},"RunMode.MULTIRUN")))),(0,i.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,i.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,i.mdx)("h5",{parentName:"div"},(0,i.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,i.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,i.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,i.mdx)("div",{parentName:"div",className:"admonition-content"},(0,i.mdx)("p",{parentName:"div"},"Hydra composes configs lazily at job launching time. If you change code or configs after launching a job/sweep, the final\ncomposed configs might be impacted."))),(0,i.mdx)("h3",{id:"sweeping-via-hydrasweeperparams"},"Sweeping via ",(0,i.mdx)("inlineCode",{parentName:"h3"},"hydra.sweeper.params")),(0,i.mdx)(o.C,{to:"examples/tutorials/basic/running_your_hydra_app/5_basic_sweep",mdxType:"ExampleGithubLink"}),(0,i.mdx)("p",null,"You can also define sweeping in the input configs by overriding\n",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.sweeper.params"),". Using the above example, the same multirun could be achieved via the following config."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml"},"hydra:\n sweeper:\n params:\n db: mysql,postgresql\n schema: warehouse,support,school\n")),(0,i.mdx)("p",null,"The syntax are consistent for both input configs and commandline overrides.\nIf a sweep is specified in both an input config and at the command line,\nthen the commandline sweep will take precedence over the sweep defined\nin the input config. If we run the same application with the above input config and a new commandline override:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="$ python my_app.py -m db=mysql"',title:'"$',python:!0,"my_app.py":!0,"-m":!0,db:'mysql"'},"[2021-01-20 17:25:03,317][HYDRA] Launching 3 jobs locally\n[2021-01-20 17:25:03,318][HYDRA] #0 : db=mysql schema=warehouse\n[2021-01-20 17:25:03,458][HYDRA] #1 : db=mysql schema=support\n[2021-01-20 17:25:03,602][HYDRA] #2 : db=mysql schema=school\n")),(0,i.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,i.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,i.mdx)("h5",{parentName:"div"},(0,i.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,i.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,i.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"info")),(0,i.mdx)("div",{parentName:"div",className:"admonition-content"},(0,i.mdx)("p",{parentName:"div"},"The above configuration methods only apply to Hydra's default ",(0,i.mdx)("inlineCode",{parentName:"p"},"BasicSweeper")," for now. For other sweepers, please check out the\ncorresponding documentations."))),(0,i.mdx)("h3",{id:"additional-sweep-types"},"Additional sweep types"),(0,i.mdx)("p",null,"Hydra supports other kinds of sweeps, e.g.:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python"},"x=range(1,10) # 1-9\nschema=glob(*) # warehouse,support,school\nschema=glob(*,exclude=w*) # support,school\n")),(0,i.mdx)("p",null,"See the ",(0,i.mdx)("a",{parentName:"p",href:"/docs/advanced/override_grammar/extended"},"Extended Override syntax")," for details."),(0,i.mdx)("h3",{id:"sweeper"},"Sweeper"),(0,i.mdx)("p",null,"The default sweeping logic is built into Hydra. Additional sweepers are available as plugins.\nFor example, the ",(0,i.mdx)("a",{parentName:"p",href:"/docs/plugins/ax_sweeper"},"Ax Sweeper")," can automatically find the best parameter combination!"),(0,i.mdx)("h3",{id:"launcher"},"Launcher"),(0,i.mdx)("p",null,"By default, Hydra runs your multi-run jobs locally and serially.\nOther launchers are available as plugins for launching in parallel and on different clusters. For example, the ",(0,i.mdx)("a",{parentName:"p",href:"/docs/plugins/joblib_launcher"},"JobLib Launcher"),"\ncan execute the different parameter combinations in parallel on your local machine using multi-processing."))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/3955c41d.cb4319cb.js b/assets/js/3955c41d.cb4319cb.js deleted file mode 100644 index ffca325aef..0000000000 --- a/assets/js/3955c41d.cb4319cb.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[7603],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>d,MDXProvider:()=>u,mdx:()=>y,useMDXComponents:()=>s,withMDXComponents:()=>p});var t=a(96540);function r(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(r[a]=e[a]);return r}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(r[a]=e[a])}return r}var d=t.createContext({}),p=function(e){return function(n){var a=s(n.components);return t.createElement(e,i({},n,{components:a}))}},s=function(e){var n=t.useContext(d),a=n;return e&&(a="function"==typeof e?e(n):l(l({},n),e)),a},u=function(e){var n=s(e.components);return t.createElement(d.Provider,{value:n},e.children)},c={inlineCode:"code",wrapper:function(e){var n=e.children;return t.createElement(t.Fragment,{},n)}},h=t.forwardRef((function(e,n){var a=e.components,r=e.mdxType,i=e.originalType,o=e.parentName,d=m(e,["components","mdxType","originalType","parentName"]),p=s(a),u=r,h=p["".concat(o,".").concat(u)]||p[u]||c[u]||i;return a?t.createElement(h,l(l({ref:n},d),{},{components:a})):t.createElement(h,l({ref:n},d))}));function y(e,n){var a=arguments,r=n&&n.mdxType;if("string"==typeof e||r){var i=a.length,o=new Array(i);o[0]=h;var l={};for(var m in n)hasOwnProperty.call(n,m)&&(l[m]=n[m]);l.originalType=e,l.mdxType="string"==typeof e?e:r,o[1]=l;for(var d=2;d{a.d(n,{A:()=>m,C:()=>d});var t=a(58168),r=a(96540),i=a(75489),o=a(44586),l=a(74098);function m(e){return r.createElement(i.default,(0,t.A)({},e,{to:(n=e.to,m=(0,l.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(a=null==m?void 0:m.name)?a:"current"]+n),target:"_blank"}));var n,a,m}function d(e){var n,a=null!=(n=e.text)?n:"Example (Click Here)";return r.createElement(m,e,r.createElement("span",null,"\xa0"),r.createElement("img",{src:"https://img.shields.io/badge/-"+a+"-informational",alt:"Example (Click Here)"}))}},58574:(e,n,a)=>{a.r(n),a.d(n,{contentTitle:()=>d,default:()=>c,frontMatter:()=>m,metadata:()=>p,toc:()=>s});var t=a(58168),r=a(98587),i=(a(96540),a(15680)),o=a(49595),l=["components"],m={id:"multi-run",title:"Multi-run",sidebar_label:"Multi-run"},d=void 0,p={unversionedId:"tutorials/basic/running_your_app/multi-run",id:"tutorials/basic/running_your_app/multi-run",title:"Multi-run",description:"Sometimes you want to run the same application with multiple different configurations.",source:"@site/docs/tutorials/basic/running_your_app/2_multirun.md",sourceDirName:"tutorials/basic/running_your_app",slug:"/tutorials/basic/running_your_app/multi-run",permalink:"/docs/tutorials/basic/running_your_app/multi-run",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/tutorials/basic/running_your_app/2_multirun.md",tags:[],version:"current",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:2,frontMatter:{id:"multi-run",title:"Multi-run",sidebar_label:"Multi-run"},sidebar:"docs",previous:{title:"Putting it all together",permalink:"/docs/tutorials/basic/your_first_app/composition"},next:{title:"Output/Working directory",permalink:"/docs/tutorials/basic/running_your_app/working_directory"}},s=[{value:"Configure hydra.mode (new in Hydra 1.2)",id:"configure-hydramode-new-in-hydra-12",children:[],level:3},{value:"--multirun (-m) from the command-line",id:"--multirun--m-from-the-command-line",children:[],level:3},{value:"Sweeping via hydra.sweeper.params",id:"sweeping-via-hydrasweeperparams",children:[],level:3},{value:"Additional sweep types",id:"additional-sweep-types",children:[],level:3},{value:"Sweeper",id:"sweeper",children:[],level:3},{value:"Launcher",id:"launcher",children:[],level:3}],u={toc:s};function c(e){var n=e.components,a=(0,r.A)(e,l);return(0,i.mdx)("wrapper",(0,t.A)({},u,a,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Sometimes you want to run the same application with multiple different configurations.",(0,i.mdx)("br",{parentName:"p"}),"\n","E.g. running a performance test on each of the databases with each of the schemas."),(0,i.mdx)("p",null,"You can multirun a Hydra application via either commandline or configuration:"),(0,i.mdx)("h3",{id:"configure-hydramode-new-in-hydra-12"},"Configure ",(0,i.mdx)("inlineCode",{parentName:"h3"},"hydra.mode")," (new in Hydra 1.2)"),(0,i.mdx)("p",null,"You can configure ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.mode")," in any supported way. The legal values are ",(0,i.mdx)("inlineCode",{parentName:"p"},"RUN")," and ",(0,i.mdx)("inlineCode",{parentName:"p"},"MULTIRUN"),".\nThe following shows how to override from the command-line and sweep over all combinations of the dbs and schemas.\nSetting ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.mode=MULTIRUN")," in your input config would make your application multi-run by default."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="$ python my_app.py hydra.mode=MULTIRUN db=mysql,postgresql schema=warehouse,support,school"',title:'"$',python:!0,"my_app.py":!0,"hydra.mode":"MULTIRUN",db:"mysql,postgresql",schema:'warehouse,support,school"'},"[2021-01-20 17:25:03,317][HYDRA] Launching 6 jobs locally\n[2021-01-20 17:25:03,318][HYDRA] #0 : db=mysql schema=warehouse\n[2021-01-20 17:25:03,458][HYDRA] #1 : db=mysql schema=support\n[2021-01-20 17:25:03,602][HYDRA] #2 : db=mysql schema=school\n[2021-01-20 17:25:03,755][HYDRA] #3 : db=postgresql schema=warehouse\n[2021-01-20 17:25:03,895][HYDRA] #4 : db=postgresql schema=support\n[2021-01-20 17:25:04,040][HYDRA] #5 : db=postgresql schema=school\n")),(0,i.mdx)("p",null,"The printed configurations have been omitted for brevity."),(0,i.mdx)("h3",{id:"--multirun--m-from-the-command-line"},(0,i.mdx)("inlineCode",{parentName:"h3"},"--multirun (-m)")," from the command-line"),(0,i.mdx)("p",null,"You can achieve the above from command-line as well:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"python my_app.py --multirun db=mysql,postgresql schema=warehouse,support,school\n")),(0,i.mdx)("p",null,"or "),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-commandline"},"python my_app.py -m db=mysql,postgresql schema=warehouse,support,school\n")),(0,i.mdx)("p",null,"You can access ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.mode")," at runtime to determine whether the application is in RUN or MULTIRUN mode. Check ",(0,i.mdx)("a",{parentName:"p",href:"/docs/configure_hydra/intro"},"here"),"\non how to access Hydra config at run time."),(0,i.mdx)("p",null,"If conflicts arise (e.g., ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.mode=RUN")," and the application was run with ",(0,i.mdx)("inlineCode",{parentName:"p"},"--multirun"),"), Hydra will determine the value of ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.mode"),"\nat run time. The following table shows what runtime ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.mode")," value you'd get with different input configs and commandline combinations."),(0,i.mdx)("table",null,(0,i.mdx)("thead",{parentName:"table"},(0,i.mdx)("tr",{parentName:"thead"},(0,i.mdx)("th",{parentName:"tr",align:null}),(0,i.mdx)("th",{parentName:"tr",align:null},"No multirun commandline flag"),(0,i.mdx)("th",{parentName:"tr",align:null},"--multirun ( -m)"))),(0,i.mdx)("tbody",{parentName:"table"},(0,i.mdx)("tr",{parentName:"tbody"},(0,i.mdx)("td",{parentName:"tr",align:null},"hydra.mode=RUN"),(0,i.mdx)("td",{parentName:"tr",align:null},"RunMode.RUN"),(0,i.mdx)("td",{parentName:"tr",align:null},"RunMode.MULTIRUN (with UserWarning)")),(0,i.mdx)("tr",{parentName:"tbody"},(0,i.mdx)("td",{parentName:"tr",align:null},"hydra.mode=MULTIRUN"),(0,i.mdx)("td",{parentName:"tr",align:null},"RunMode.MULTIRUN"),(0,i.mdx)("td",{parentName:"tr",align:null},"RunMode.MULTIRUN")),(0,i.mdx)("tr",{parentName:"tbody"},(0,i.mdx)("td",{parentName:"tr",align:null},"hydra.mode=None (default)"),(0,i.mdx)("td",{parentName:"tr",align:null},"RunMode.RUN"),(0,i.mdx)("td",{parentName:"tr",align:null},"RunMode.MULTIRUN")))),(0,i.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,i.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,i.mdx)("h5",{parentName:"div"},(0,i.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,i.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,i.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,i.mdx)("div",{parentName:"div",className:"admonition-content"},(0,i.mdx)("p",{parentName:"div"},"Hydra composes configs lazily at job launching time. If you change code or configs after launching a job/sweep, the final\ncomposed configs might be impacted."))),(0,i.mdx)("h3",{id:"sweeping-via-hydrasweeperparams"},"Sweeping via ",(0,i.mdx)("inlineCode",{parentName:"h3"},"hydra.sweeper.params")),(0,i.mdx)(o.C,{to:"examples/tutorials/basic/running_your_hydra_app/5_basic_sweep",mdxType:"ExampleGithubLink"}),(0,i.mdx)("p",null,"You can also define sweeping in the input configs by overriding\n",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.sweeper.params"),". Using the above example, the same multirun could be achieved via the following config."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml"},"hydra:\n sweeper:\n params:\n db: mysql,postgresql\n schema: warehouse,support,school\n")),(0,i.mdx)("p",null,"The syntax are consistent for both input configs and commandline overrides.\nIf a sweep is specified in both an input config and at the command line,\nthen the commandline sweep will take precedence over the sweep defined\nin the input config. If we run the same application with the above input config and a new commandline override:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="$ python my_app.py -m db=mysql"',title:'"$',python:!0,"my_app.py":!0,"-m":!0,db:'mysql"'},"[2021-01-20 17:25:03,317][HYDRA] Launching 3 jobs locally\n[2021-01-20 17:25:03,318][HYDRA] #0 : db=mysql schema=warehouse\n[2021-01-20 17:25:03,458][HYDRA] #1 : db=mysql schema=support\n[2021-01-20 17:25:03,602][HYDRA] #2 : db=mysql schema=school\n")),(0,i.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,i.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,i.mdx)("h5",{parentName:"div"},(0,i.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,i.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,i.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"info")),(0,i.mdx)("div",{parentName:"div",className:"admonition-content"},(0,i.mdx)("p",{parentName:"div"},"The above configuration methods only apply to Hydra's default ",(0,i.mdx)("inlineCode",{parentName:"p"},"BasicSweeper")," for now. For other sweepers, please check out the\ncorresponding documentations."))),(0,i.mdx)("h3",{id:"additional-sweep-types"},"Additional sweep types"),(0,i.mdx)("p",null,"Hydra supports other kinds of sweeps, e.g.:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python"},"x=range(1,10) # 1-9\nschema=glob(*) # warehouse,support,school\nschema=glob(*,exclude=w*) # support,school\n")),(0,i.mdx)("p",null,"See the ",(0,i.mdx)("a",{parentName:"p",href:"/docs/advanced/override_grammar/extended"},"Extended Override syntax")," for details."),(0,i.mdx)("h3",{id:"sweeper"},"Sweeper"),(0,i.mdx)("p",null,"The default sweeping logic is built into Hydra. Additional sweepers are available as plugins.\nFor example, the ",(0,i.mdx)("a",{parentName:"p",href:"/docs/plugins/ax_sweeper"},"Ax Sweeper")," can automatically find the best parameter combination!"),(0,i.mdx)("h3",{id:"launcher"},"Launcher"),(0,i.mdx)("p",null,"By default, Hydra runs your multi-run jobs locally and serially.\nOther launchers are available as plugins for launching in parallel and on different clusters. For example, the ",(0,i.mdx)("a",{parentName:"p",href:"/docs/plugins/joblib_launcher"},"JobLib Launcher"),"\ncan execute the different parameter combinations in parallel on your local machine using multi-processing."))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/395e7b7b.0de7c25f.js b/assets/js/395e7b7b.0de7c25f.js deleted file mode 100644 index df037c4a00..0000000000 --- a/assets/js/395e7b7b.0de7c25f.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[1653],{15680:(e,t,r)=>{r.r(t),r.d(t,{MDXContext:()=>l,MDXProvider:()=>c,mdx:()=>v,useMDXComponents:()=>u,withMDXComponents:()=>p});var n=r(96540);function a(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(a[r]=e[r]);return a}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(a[r]=e[r])}return a}var l=n.createContext({}),p=function(e){return function(t){var r=u(t.components);return n.createElement(e,o({},t,{components:r}))}},u=function(e){var t=n.useContext(l),r=t;return e&&(r="function"==typeof e?e(t):s(s({},t),e)),r},c=function(e){var t=u(e.components);return n.createElement(l.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},f=n.forwardRef((function(e,t){var r=e.components,a=e.mdxType,o=e.originalType,i=e.parentName,l=d(e,["components","mdxType","originalType","parentName"]),p=u(r),c=a,f=p["".concat(i,".").concat(c)]||p[c]||m[c]||o;return r?n.createElement(f,s(s({ref:t},l),{},{components:r})):n.createElement(f,s({ref:t},l))}));function v(e,t){var r=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var o=r.length,i=new Array(o);i[0]=f;var s={};for(var d in t)hasOwnProperty.call(t,d)&&(s[d]=t[d]);s.originalType=e,s.mdxType="string"==typeof e?e:a,i[1]=s;for(var l=2;l{r.r(t),r.d(t,{contentTitle:()=>d,default:()=>c,frontMatter:()=>s,metadata:()=>l,toc:()=>p});var n=r(58168),a=r(98587),o=(r(96540),r(15680)),i=["components"],s={id:"defaults_list_override",title:"Defaults List Overrides"},d=void 0,l={unversionedId:"upgrades/1.0_to_1.1/defaults_list_override",id:"upgrades/1.0_to_1.1/defaults_list_override",title:"Defaults List Overrides",description:"Hydra versions prior to 1.1 supported overriding of Hydra config groups via the Defaults List in this manner:",source:"@site/docs/upgrades/1.0_to_1.1/defaults_list_override.md",sourceDirName:"upgrades/1.0_to_1.1",slug:"/upgrades/1.0_to_1.1/defaults_list_override",permalink:"/docs/upgrades/1.0_to_1.1/defaults_list_override",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/upgrades/1.0_to_1.1/defaults_list_override.md",tags:[],version:"current",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"defaults_list_override",title:"Defaults List Overrides"},sidebar:"docs",previous:{title:"Changes to default composition order",permalink:"/docs/upgrades/1.0_to_1.1/default_composition_order"},next:{title:"Defaults List interpolation",permalink:"/docs/upgrades/1.0_to_1.1/defaults_list_interpolation"}},p=[],u={toc:p};function c(e){var t=e.components,r=(0,a.A)(e,i);return(0,o.mdx)("wrapper",(0,n.A)({},u,r,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"Hydra versions prior to 1.1 supported overriding of Hydra config groups via the Defaults List in this manner:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{3}","{3}":!0},"defaults:\n - model: resnet50\n - hydra/launcher: submitit\n")),(0,o.mdx)("p",null,"As of Hydra 1.1, Config group overrides must be marked explicitly with the ",(0,o.mdx)("inlineCode",{parentName:"p"},"override")," keyword:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{3}","{3}":!0},"defaults:\n - model: resnet50\n - override hydra/launcher: submitit\n")),(0,o.mdx)("p",null,"The Defaults List is described ",(0,o.mdx)("a",{parentName:"p",href:"/docs/advanced/defaults_list"},"here"),"."),(0,o.mdx)("div",{className:"admonition admonition-warning alert alert--danger"},(0,o.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,o.mdx)("h5",{parentName:"div"},(0,o.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,o.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"12",height:"16",viewBox:"0 0 12 16"},(0,o.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M5.05.31c.81 2.17.41 3.38-.52 4.31C3.55 5.67 1.98 6.45.9 7.98c-1.45 2.05-1.7 6.53 3.53 7.7-2.2-1.16-2.67-4.52-.3-6.61-.61 2.03.53 3.33 1.94 2.86 1.39-.47 2.3.53 2.27 1.67-.02.78-.31 1.44-1.13 1.81 3.42-.59 4.78-3.42 4.78-5.56 0-2.84-2.53-3.22-1.25-5.61-1.52.13-2.03 1.13-1.89 2.75.09 1.08-1.02 1.8-1.86 1.33-.67-.41-.66-1.19-.06-1.78C8.18 5.31 8.68 2.45 5.05.32L5.03.3l.02.01z"}))),"warning")),(0,o.mdx)("div",{parentName:"div",className:"admonition-content"},(0,o.mdx)("p",{parentName:"div"},"Omitting the ",(0,o.mdx)("inlineCode",{parentName:"p"},"override")," keyword when overriding Hydra's config groups will result in an error in Hydra 1.2"))))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/395e7b7b.6dd1b4f1.js b/assets/js/395e7b7b.6dd1b4f1.js new file mode 100644 index 0000000000..1934e154eb --- /dev/null +++ b/assets/js/395e7b7b.6dd1b4f1.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[1653],{15680:(e,t,r)=>{r.r(t),r.d(t,{MDXContext:()=>l,MDXProvider:()=>c,mdx:()=>v,useMDXComponents:()=>u,withMDXComponents:()=>p});var n=r(96540);function a(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(a[r]=e[r]);return a}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(a[r]=e[r])}return a}var l=n.createContext({}),p=function(e){return function(t){var r=u(t.components);return n.createElement(e,o({},t,{components:r}))}},u=function(e){var t=n.useContext(l),r=t;return e&&(r="function"==typeof e?e(t):s(s({},t),e)),r},c=function(e){var t=u(e.components);return n.createElement(l.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},f=n.forwardRef((function(e,t){var r=e.components,a=e.mdxType,o=e.originalType,i=e.parentName,l=d(e,["components","mdxType","originalType","parentName"]),p=u(r),c=a,f=p["".concat(i,".").concat(c)]||p[c]||m[c]||o;return r?n.createElement(f,s(s({ref:t},l),{},{components:r})):n.createElement(f,s({ref:t},l))}));function v(e,t){var r=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var o=r.length,i=new Array(o);i[0]=f;var s={};for(var d in t)hasOwnProperty.call(t,d)&&(s[d]=t[d]);s.originalType=e,s.mdxType="string"==typeof e?e:a,i[1]=s;for(var l=2;l{r.r(t),r.d(t,{contentTitle:()=>d,default:()=>c,frontMatter:()=>s,metadata:()=>l,toc:()=>p});var n=r(58168),a=r(98587),o=(r(96540),r(15680)),i=["components"],s={id:"defaults_list_override",title:"Defaults List Overrides"},d=void 0,l={unversionedId:"upgrades/1.0_to_1.1/defaults_list_override",id:"upgrades/1.0_to_1.1/defaults_list_override",title:"Defaults List Overrides",description:"Hydra versions prior to 1.1 supported overriding of Hydra config groups via the Defaults List in this manner:",source:"@site/docs/upgrades/1.0_to_1.1/defaults_list_override.md",sourceDirName:"upgrades/1.0_to_1.1",slug:"/upgrades/1.0_to_1.1/defaults_list_override",permalink:"/docs/upgrades/1.0_to_1.1/defaults_list_override",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/upgrades/1.0_to_1.1/defaults_list_override.md",tags:[],version:"current",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"defaults_list_override",title:"Defaults List Overrides"},sidebar:"docs",previous:{title:"Changes to default composition order",permalink:"/docs/upgrades/1.0_to_1.1/default_composition_order"},next:{title:"Defaults List interpolation",permalink:"/docs/upgrades/1.0_to_1.1/defaults_list_interpolation"}},p=[],u={toc:p};function c(e){var t=e.components,r=(0,a.A)(e,i);return(0,o.mdx)("wrapper",(0,n.A)({},u,r,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"Hydra versions prior to 1.1 supported overriding of Hydra config groups via the Defaults List in this manner:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{3}","{3}":!0},"defaults:\n - model: resnet50\n - hydra/launcher: submitit\n")),(0,o.mdx)("p",null,"As of Hydra 1.1, Config group overrides must be marked explicitly with the ",(0,o.mdx)("inlineCode",{parentName:"p"},"override")," keyword:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{3}","{3}":!0},"defaults:\n - model: resnet50\n - override hydra/launcher: submitit\n")),(0,o.mdx)("p",null,"The Defaults List is described ",(0,o.mdx)("a",{parentName:"p",href:"/docs/advanced/defaults_list"},"here"),"."),(0,o.mdx)("div",{className:"admonition admonition-warning alert alert--danger"},(0,o.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,o.mdx)("h5",{parentName:"div"},(0,o.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,o.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"12",height:"16",viewBox:"0 0 12 16"},(0,o.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M5.05.31c.81 2.17.41 3.38-.52 4.31C3.55 5.67 1.98 6.45.9 7.98c-1.45 2.05-1.7 6.53 3.53 7.7-2.2-1.16-2.67-4.52-.3-6.61-.61 2.03.53 3.33 1.94 2.86 1.39-.47 2.3.53 2.27 1.67-.02.78-.31 1.44-1.13 1.81 3.42-.59 4.78-3.42 4.78-5.56 0-2.84-2.53-3.22-1.25-5.61-1.52.13-2.03 1.13-1.89 2.75.09 1.08-1.02 1.8-1.86 1.33-.67-.41-.66-1.19-.06-1.78C8.18 5.31 8.68 2.45 5.05.32L5.03.3l.02.01z"}))),"warning")),(0,o.mdx)("div",{parentName:"div",className:"admonition-content"},(0,o.mdx)("p",{parentName:"div"},"Omitting the ",(0,o.mdx)("inlineCode",{parentName:"p"},"override")," keyword when overriding Hydra's config groups will result in an error in Hydra 1.2"))))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/3989901c.710898a3.js b/assets/js/3989901c.710898a3.js deleted file mode 100644 index ff1d3e430f..0000000000 --- a/assets/js/3989901c.710898a3.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3065],{15680:(e,r,t)=>{t.r(r),t.d(r,{MDXContext:()=>u,MDXProvider:()=>m,mdx:()=>g,useMDXComponents:()=>c,withMDXComponents:()=>p});var n=t(96540);function o(e,r,t){return r in e?Object.defineProperty(e,r,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[r]=t,e}function i(){return i=Object.assign||function(e){for(var r=1;r=0||(o[t]=e[t]);return o}(e,r);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(o[t]=e[t])}return o}var u=n.createContext({}),p=function(e){return function(r){var t=c(r.components);return n.createElement(e,i({},r,{components:t}))}},c=function(e){var r=n.useContext(u),t=r;return e&&(t="function"==typeof e?e(r):l(l({},r),e)),t},m=function(e){var r=c(e.components);return n.createElement(u.Provider,{value:r},e.children)},s={inlineCode:"code",wrapper:function(e){var r=e.children;return n.createElement(n.Fragment,{},r)}},y=n.forwardRef((function(e,r){var t=e.components,o=e.mdxType,i=e.originalType,a=e.parentName,u=d(e,["components","mdxType","originalType","parentName"]),p=c(t),m=o,y=p["".concat(a,".").concat(m)]||p[m]||s[m]||i;return t?n.createElement(y,l(l({ref:r},u),{},{components:t})):n.createElement(y,l({ref:r},u))}));function g(e,r){var t=arguments,o=r&&r.mdxType;if("string"==typeof e||o){var i=t.length,a=new Array(i);a[0]=y;var l={};for(var d in r)hasOwnProperty.call(r,d)&&(l[d]=r[d]);l.originalType=e,l.mdxType="string"==typeof e?e:o,a[1]=l;for(var u=2;u{t.d(r,{A:()=>d,C:()=>u});var n=t(58168),o=t(96540),i=t(75489),a=t(44586),l=t(74098);function d(e){return o.createElement(i.default,(0,n.A)({},e,{to:(r=e.to,d=(0,l.useActiveVersion)(),(0,a.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==d?void 0:d.name)?t:"current"]+r),target:"_blank"}));var r,t,d}function u(e){var r,t=null!=(r=e.text)?r:"Example (Click Here)";return o.createElement(d,e,o.createElement("span",null,"\xa0"),o.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},73924:(e,r,t)=>{t.r(r),t.d(r,{contentTitle:()=>u,default:()=>s,frontMatter:()=>d,metadata:()=>p,toc:()=>c});var n=t(58168),o=t(98587),i=(t(96540),t(15680)),a=t(49595),l=["components"],d={id:"working_directory",title:"Output/Working directory",sidebar_label:"Output/Working directory"},u=void 0,p={unversionedId:"tutorials/basic/running_your_app/working_directory",id:"version-1.1/tutorials/basic/running_your_app/working_directory",title:"Output/Working directory",description:"Hydra solves the problem of your needing to specify a new output directory for each run, by",source:"@site/versioned_docs/version-1.1/tutorials/basic/running_your_app/3_working_directory.md",sourceDirName:"tutorials/basic/running_your_app",slug:"/tutorials/basic/running_your_app/working_directory",permalink:"/docs/1.1/tutorials/basic/running_your_app/working_directory",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/tutorials/basic/running_your_app/3_working_directory.md",tags:[],version:"1.1",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:3,frontMatter:{id:"working_directory",title:"Output/Working directory",sidebar_label:"Output/Working directory"},sidebar:"version-1.1/docs",previous:{title:"Multi-run",permalink:"/docs/1.1/tutorials/basic/running_your_app/multi-run"},next:{title:"Logging",permalink:"/docs/1.1/tutorials/basic/running_your_app/logging"}},c=[{value:"Changing or disabling the output subdir",id:"changing-or-disabling-the-output-subdir",children:[],level:3},{value:"Original working directory",id:"original-working-directory",children:[],level:3}],m={toc:c};function s(e){var r=e.components,t=(0,o.A)(e,l);return(0,i.mdx)("wrapper",(0,n.A)({},m,t,{components:r,mdxType:"MDXLayout"}),(0,i.mdx)(a.C,{to:"examples/tutorials/basic/running_your_hydra_app/3_working_directory",mdxType:"ExampleGithubLink"}),(0,i.mdx)("p",null,"Hydra solves the problem of your needing to specify a new output directory for each run, by\ncreating a directory for each run and executing your code within that working directory."),(0,i.mdx)("p",null,"The working directory is used to:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"Store the output for the application (For example, a database dump file)"),(0,i.mdx)("li",{parentName:"ul"},"Store the Hydra output for the run (Configuration, Logs etc)")),(0,i.mdx)("p",null,"Every time you run the app, a new working directory is created:"),(0,i.mdx)("p",null,"Python file: ",(0,i.mdx)("inlineCode",{parentName:"p"},"my_app.py")),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python"},'import os\nimport hydra\nfrom omegaconf import DictConfig\n\n@hydra.main()\ndef my_app(cfg: DictConfig) -> None:\n print("Working directory : {}".format(os.getcwd()))\n\n$ python my_app.py\nWorking directory : /home/omry/dev/hydra/outputs/2019-09-25/15-16-17\n\n$ python my_app.py\nWorking directory : /home/omry/dev/hydra/outputs/2019-09-25/15-16-19\n')),(0,i.mdx)("p",null,"Let's take a look at one of the working directories:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text"},"$ tree outputs/2019-09-25/15-16-17\noutputs/2019-09-25/15-16-17\n\u251c\u2500\u2500 .hydra\n\u2502 \u251c\u2500\u2500 config.yaml\n\u2502 \u251c\u2500\u2500 hydra.yaml\n\u2502 \u2514\u2500\u2500 overrides.yaml\n\u2514\u2500\u2500 my_app.log\n")),(0,i.mdx)("p",null,"We have the Hydra output directory (",(0,i.mdx)("inlineCode",{parentName:"p"},".hydra")," by default), and the application log file.\nInside the Hydra output directory we have:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"config.yaml"),": A dump of the user specified configuration"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"hydra.yaml"),": A dump of the Hydra configuration"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"overrides.yaml"),": The command line overrides used")),(0,i.mdx)("p",null,"And in the main output directory:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"my_app.log"),": A log file created for this run")),(0,i.mdx)("h3",{id:"changing-or-disabling-the-output-subdir"},"Changing or disabling the output subdir"),(0,i.mdx)("p",null,"You can change the ",(0,i.mdx)("inlineCode",{parentName:"p"},".hydra")," subdirectory name by overriding ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.output_subdir"),".\nYou can disable its creation by overriding ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.output_subdir")," to ",(0,i.mdx)("inlineCode",{parentName:"p"},"null"),". "),(0,i.mdx)("h3",{id:"original-working-directory"},"Original working directory"),(0,i.mdx)("p",null,"You can still access the original working directory via ",(0,i.mdx)("inlineCode",{parentName:"p"},"get_original_cwd()")," and ",(0,i.mdx)("inlineCode",{parentName:"p"},"to_absolute_path()")," in ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.utils"),":"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python"},'from hydra.utils import get_original_cwd, to_absolute_path\n\n@hydra.main()\ndef my_app(_cfg: DictConfig) -> None:\n print(f"Current working directory : {os.getcwd()}")\n print(f"Orig working directory : {get_original_cwd()}")\n print(f"to_absolute_path(\'foo\') : {to_absolute_path(\'foo\')}")\n print(f"to_absolute_path(\'/foo\') : {to_absolute_path(\'/foo\')}")\n\nif __name__ == "__main__":\n my_app()\n')),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="$ python examples/tutorial/8_working_directory/original_cwd.py"',title:'"$',python:!0,'examples/tutorial/8_working_directory/original_cwd.py"':!0},"Current working directory : /Users/omry/dev/hydra/outputs/2019-10-23/10-53-03\nOriginal working directory : /Users/omry/dev/hydra\nto_absolute_path('foo') : /Users/omry/dev/hydra/foo\nto_absolute_path('/foo') : /foo\n")),(0,i.mdx)("p",null,"The name of the generated working directories can be ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.1/configure_hydra/workdir"},"customized"),"."))}s.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/3989901c.b9a130a5.js b/assets/js/3989901c.b9a130a5.js new file mode 100644 index 0000000000..bc0af410ac --- /dev/null +++ b/assets/js/3989901c.b9a130a5.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3065],{15680:(e,r,t)=>{t.r(r),t.d(r,{MDXContext:()=>u,MDXProvider:()=>m,mdx:()=>g,useMDXComponents:()=>c,withMDXComponents:()=>p});var n=t(96540);function o(e,r,t){return r in e?Object.defineProperty(e,r,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[r]=t,e}function i(){return i=Object.assign||function(e){for(var r=1;r=0||(o[t]=e[t]);return o}(e,r);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(o[t]=e[t])}return o}var u=n.createContext({}),p=function(e){return function(r){var t=c(r.components);return n.createElement(e,i({},r,{components:t}))}},c=function(e){var r=n.useContext(u),t=r;return e&&(t="function"==typeof e?e(r):l(l({},r),e)),t},m=function(e){var r=c(e.components);return n.createElement(u.Provider,{value:r},e.children)},s={inlineCode:"code",wrapper:function(e){var r=e.children;return n.createElement(n.Fragment,{},r)}},y=n.forwardRef((function(e,r){var t=e.components,o=e.mdxType,i=e.originalType,a=e.parentName,u=d(e,["components","mdxType","originalType","parentName"]),p=c(t),m=o,y=p["".concat(a,".").concat(m)]||p[m]||s[m]||i;return t?n.createElement(y,l(l({ref:r},u),{},{components:t})):n.createElement(y,l({ref:r},u))}));function g(e,r){var t=arguments,o=r&&r.mdxType;if("string"==typeof e||o){var i=t.length,a=new Array(i);a[0]=y;var l={};for(var d in r)hasOwnProperty.call(r,d)&&(l[d]=r[d]);l.originalType=e,l.mdxType="string"==typeof e?e:o,a[1]=l;for(var u=2;u{t.d(r,{A:()=>d,C:()=>u});var n=t(58168),o=t(96540),i=t(75489),a=t(44586),l=t(74098);function d(e){return o.createElement(i.default,(0,n.A)({},e,{to:(r=e.to,d=(0,l.useActiveVersion)(),(0,a.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(t=null==d?void 0:d.name)?t:"current"]+r),target:"_blank"}));var r,t,d}function u(e){var r,t=null!=(r=e.text)?r:"Example (Click Here)";return o.createElement(d,e,o.createElement("span",null,"\xa0"),o.createElement("img",{src:"https://img.shields.io/badge/-"+t+"-informational",alt:"Example (Click Here)"}))}},73924:(e,r,t)=>{t.r(r),t.d(r,{contentTitle:()=>u,default:()=>s,frontMatter:()=>d,metadata:()=>p,toc:()=>c});var n=t(58168),o=t(98587),i=(t(96540),t(15680)),a=t(49595),l=["components"],d={id:"working_directory",title:"Output/Working directory",sidebar_label:"Output/Working directory"},u=void 0,p={unversionedId:"tutorials/basic/running_your_app/working_directory",id:"version-1.1/tutorials/basic/running_your_app/working_directory",title:"Output/Working directory",description:"Hydra solves the problem of your needing to specify a new output directory for each run, by",source:"@site/versioned_docs/version-1.1/tutorials/basic/running_your_app/3_working_directory.md",sourceDirName:"tutorials/basic/running_your_app",slug:"/tutorials/basic/running_your_app/working_directory",permalink:"/docs/1.1/tutorials/basic/running_your_app/working_directory",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.1/tutorials/basic/running_your_app/3_working_directory.md",tags:[],version:"1.1",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:3,frontMatter:{id:"working_directory",title:"Output/Working directory",sidebar_label:"Output/Working directory"},sidebar:"version-1.1/docs",previous:{title:"Multi-run",permalink:"/docs/1.1/tutorials/basic/running_your_app/multi-run"},next:{title:"Logging",permalink:"/docs/1.1/tutorials/basic/running_your_app/logging"}},c=[{value:"Changing or disabling the output subdir",id:"changing-or-disabling-the-output-subdir",children:[],level:3},{value:"Original working directory",id:"original-working-directory",children:[],level:3}],m={toc:c};function s(e){var r=e.components,t=(0,o.A)(e,l);return(0,i.mdx)("wrapper",(0,n.A)({},m,t,{components:r,mdxType:"MDXLayout"}),(0,i.mdx)(a.C,{to:"examples/tutorials/basic/running_your_hydra_app/3_working_directory",mdxType:"ExampleGithubLink"}),(0,i.mdx)("p",null,"Hydra solves the problem of your needing to specify a new output directory for each run, by\ncreating a directory for each run and executing your code within that working directory."),(0,i.mdx)("p",null,"The working directory is used to:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"Store the output for the application (For example, a database dump file)"),(0,i.mdx)("li",{parentName:"ul"},"Store the Hydra output for the run (Configuration, Logs etc)")),(0,i.mdx)("p",null,"Every time you run the app, a new working directory is created:"),(0,i.mdx)("p",null,"Python file: ",(0,i.mdx)("inlineCode",{parentName:"p"},"my_app.py")),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python"},'import os\nimport hydra\nfrom omegaconf import DictConfig\n\n@hydra.main()\ndef my_app(cfg: DictConfig) -> None:\n print("Working directory : {}".format(os.getcwd()))\n\n$ python my_app.py\nWorking directory : /home/omry/dev/hydra/outputs/2019-09-25/15-16-17\n\n$ python my_app.py\nWorking directory : /home/omry/dev/hydra/outputs/2019-09-25/15-16-19\n')),(0,i.mdx)("p",null,"Let's take a look at one of the working directories:"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text"},"$ tree outputs/2019-09-25/15-16-17\noutputs/2019-09-25/15-16-17\n\u251c\u2500\u2500 .hydra\n\u2502 \u251c\u2500\u2500 config.yaml\n\u2502 \u251c\u2500\u2500 hydra.yaml\n\u2502 \u2514\u2500\u2500 overrides.yaml\n\u2514\u2500\u2500 my_app.log\n")),(0,i.mdx)("p",null,"We have the Hydra output directory (",(0,i.mdx)("inlineCode",{parentName:"p"},".hydra")," by default), and the application log file.\nInside the Hydra output directory we have:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"config.yaml"),": A dump of the user specified configuration"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"hydra.yaml"),": A dump of the Hydra configuration"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"overrides.yaml"),": The command line overrides used")),(0,i.mdx)("p",null,"And in the main output directory:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("inlineCode",{parentName:"li"},"my_app.log"),": A log file created for this run")),(0,i.mdx)("h3",{id:"changing-or-disabling-the-output-subdir"},"Changing or disabling the output subdir"),(0,i.mdx)("p",null,"You can change the ",(0,i.mdx)("inlineCode",{parentName:"p"},".hydra")," subdirectory name by overriding ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.output_subdir"),".\nYou can disable its creation by overriding ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.output_subdir")," to ",(0,i.mdx)("inlineCode",{parentName:"p"},"null"),". "),(0,i.mdx)("h3",{id:"original-working-directory"},"Original working directory"),(0,i.mdx)("p",null,"You can still access the original working directory via ",(0,i.mdx)("inlineCode",{parentName:"p"},"get_original_cwd()")," and ",(0,i.mdx)("inlineCode",{parentName:"p"},"to_absolute_path()")," in ",(0,i.mdx)("inlineCode",{parentName:"p"},"hydra.utils"),":"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python"},'from hydra.utils import get_original_cwd, to_absolute_path\n\n@hydra.main()\ndef my_app(_cfg: DictConfig) -> None:\n print(f"Current working directory : {os.getcwd()}")\n print(f"Orig working directory : {get_original_cwd()}")\n print(f"to_absolute_path(\'foo\') : {to_absolute_path(\'foo\')}")\n print(f"to_absolute_path(\'/foo\') : {to_absolute_path(\'/foo\')}")\n\nif __name__ == "__main__":\n my_app()\n')),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="$ python examples/tutorial/8_working_directory/original_cwd.py"',title:'"$',python:!0,'examples/tutorial/8_working_directory/original_cwd.py"':!0},"Current working directory : /Users/omry/dev/hydra/outputs/2019-10-23/10-53-03\nOriginal working directory : /Users/omry/dev/hydra\nto_absolute_path('foo') : /Users/omry/dev/hydra/foo\nto_absolute_path('/foo') : /foo\n")),(0,i.mdx)("p",null,"The name of the generated working directories can be ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.1/configure_hydra/workdir"},"customized"),"."))}s.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/39a98d83.97069c7f.js b/assets/js/39a98d83.97069c7f.js deleted file mode 100644 index 816e57c7d3..0000000000 --- a/assets/js/39a98d83.97069c7f.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3393],{15680:(e,a,t)=>{t.r(a),t.d(a,{MDXContext:()=>c,MDXProvider:()=>s,mdx:()=>v,useMDXComponents:()=>m,withMDXComponents:()=>p});var n=t(96540);function r(e,a,t){return a in e?Object.defineProperty(e,a,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[a]=t,e}function i(){return i=Object.assign||function(e){for(var a=1;a=0||(r[t]=e[t]);return r}(e,a);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(r[t]=e[t])}return r}var c=n.createContext({}),p=function(e){return function(a){var t=m(a.components);return n.createElement(e,i({},a,{components:t}))}},m=function(e){var a=n.useContext(c),t=a;return e&&(t="function"==typeof e?e(a):l(l({},a),e)),t},s=function(e){var a=m(e.components);return n.createElement(c.Provider,{value:a},e.children)},g={inlineCode:"code",wrapper:function(e){var a=e.children;return n.createElement(n.Fragment,{},a)}},u=n.forwardRef((function(e,a){var t=e.components,r=e.mdxType,i=e.originalType,o=e.parentName,c=d(e,["components","mdxType","originalType","parentName"]),p=m(t),s=r,u=p["".concat(o,".").concat(s)]||p[s]||g[s]||i;return t?n.createElement(u,l(l({ref:a},c),{},{components:t})):n.createElement(u,l({ref:a},c))}));function v(e,a){var t=arguments,r=a&&a.mdxType;if("string"==typeof e||r){var i=t.length,o=new Array(i);o[0]=u;var l={};for(var d in a)hasOwnProperty.call(a,d)&&(l[d]=a[d]);l.originalType=e,l.mdxType="string"==typeof e?e:r,o[1]=l;for(var c=2;c{t.r(a),t.d(a,{contentTitle:()=>d,default:()=>s,frontMatter:()=>l,metadata:()=>c,toc:()=>p});var n=t(58168),r=t(98587),i=(t(96540),t(15680)),o=["components"],l={id:"overriding_packages",title:"Overriding packages"},d=void 0,c={unversionedId:"advanced/overriding_packages",id:"version-1.0/advanced/overriding_packages",title:"Overriding packages",description:"Example application",source:"@site/versioned_docs/version-1.0/advanced/overriding_packages.md",sourceDirName:"advanced",slug:"/advanced/overriding_packages",permalink:"/docs/1.0/advanced/overriding_packages",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.0/advanced/overriding_packages.md",tags:[],version:"1.0",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"overriding_packages",title:"Overriding packages"},sidebar:"version-1.0/docs",previous:{title:"Extended Override syntax",permalink:"/docs/1.0/advanced/override_grammar/extended"},next:{title:"Config Search Path",permalink:"/docs/1.0/advanced/search_path"}},p=[{value:"Package specification",id:"package-specification",children:[],level:3},{value:"Overriding the package in a file via a package directive",id:"overriding-the-package-in-a-file-via-a-package-directive",children:[{value:"Examples",id:"examples",children:[{value:"A package directive with a literal",id:"a-package-directive-with-a-literal",children:[],level:5},{value:"A package directive with _group_ and _name_",id:"a-package-directive-with-_group_-and-_name_",children:[],level:5}],level:4}],level:3},{value:"Overriding the package via the defaults list",id:"overriding-the-package-via-the-defaults-list",children:[],level:3},{value:"History and future of the package directive",id:"history-and-future-of-the-package-directive",children:[],level:3}],m={toc:p};function s(e){var a=e.components,t=(0,r.A)(e,o);return(0,i.mdx)("wrapper",(0,n.A)({},m,t,{components:a,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,(0,i.mdx)("a",{parentName:"p",href:"https://github.com/facebookresearch/hydra/tree/1.0_branch/examples/advanced/package_overrides"},(0,i.mdx)("img",{parentName:"a",src:"https://img.shields.io/badge/-Example%20application-informational",alt:"Example application"}))),(0,i.mdx)("p",null,"The contents of a config file can be relocated, or replicated, within the config, via package overrides."),(0,i.mdx)("h3",{id:"package-specification"},"Package specification"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Definition of a package"',title:'"Definition',of:!0,a:!0,'package"':!0},"PACKAGE : _global_ | COMPONENT[.COMPONENT]*\nCOMPONENT : _group_ | _name_ | \\w+\n\n_global_ : the top level package (equivalent to the empty string).\n_group_ : the config group in dot notation: foo/bar/zoo.yaml -> foo.bar\n_name_ : the config file name: foo/bar/zoo.yaml -> zoo\n")),(0,i.mdx)("h3",{id:"overriding-the-package-in-a-file-via-a-package-directive"},"Overriding the package in a file via a package directive"),(0,i.mdx)("p",null,"A ",(0,i.mdx)("inlineCode",{parentName:"p"},"@package directive")," specifies a common ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.0/terminology#package"},"package")," for all nodes in the config file.\nIt must be placed at the top of each ",(0,i.mdx)("inlineCode",{parentName:"p"},"config group file"),"."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Package directive examples"',title:'"Package',directive:!0,'examples"':!0},"# @package foo.bar\n# @package _global_\n# @package _group_\n# @package _group_._name_\n# @package foo._group_._name_\n")),(0,i.mdx)("h4",{id:"examples"},"Examples"),(0,i.mdx)("h5",{id:"a-package-directive-with-a-literal"},"A package directive with a literal"),(0,i.mdx)("div",{className:"row"},(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="mysql.yaml" {1-2}',title:'"mysql.yaml"',"{1-2}":!0},"# @package foo.bar\n\ndb:\n host: localhost\n port: 3306\n"))),(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Interpretation" {1-2}',title:'"Interpretation"',"{1-2}":!0},"foo:\n bar:\n db:\n host: localhost\n port: 3306\n")))),(0,i.mdx)("h5",{id:"a-package-directive-with-_group_-and-_name_"},"A package directive with ",(0,i.mdx)("inlineCode",{parentName:"h5"},"_group_")," and ",(0,i.mdx)("inlineCode",{parentName:"h5"},"_name_")),(0,i.mdx)("div",{className:"row"},(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml" {1-2}',title:'"db/mysql.yaml"',"{1-2}":!0},"# @package _group_._name_\n\nhost: localhost\nport: 3306\n"))),(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Interpretation" {1-2}',title:'"Interpretation"',"{1-2}":!0},"db:\n mysql:\n host: localhost\n port: 3306\n")))),(0,i.mdx)("h3",{id:"overriding-the-package-via-the-defaults-list"},"Overriding the package via the defaults list"),(0,i.mdx)("p",null,"The following example adds the ",(0,i.mdx)("inlineCode",{parentName:"p"},"mysql")," config in the packages ",(0,i.mdx)("inlineCode",{parentName:"p"},"db.src")," and ",(0,i.mdx)("inlineCode",{parentName:"p"},"db.dst"),"."),(0,i.mdx)("div",{className:"row"},(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - db@db.src: mysql\n - db@db.dst: mysql\n\n\n\n\n"))),(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Interpretation"',title:'"Interpretation"'},"db:\n src:\n host: localhost\n port: 3306\n dst:\n host: localhost\n port: 3306\n")))),(0,i.mdx)("h3",{id:"history-and-future-of-the-package-directive"},"History and future of the package directive"),(0,i.mdx)("p",null,"The primary config, named in ",(0,i.mdx)("inlineCode",{parentName:"p"},"@hydra.main()")," should not have a package directive."),(0,i.mdx)("p",null,"For config files in config groups the default depends on the version:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"In ",(0,i.mdx)("strong",{parentName:"li"},"Hydra 0.11"),", there was an implicit default of ",(0,i.mdx)("inlineCode",{parentName:"li"},"_global_")),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"Hydra 1.0")," the default is ",(0,i.mdx)("inlineCode",{parentName:"li"},"_global_"),(0,i.mdx)("br",{parentName:"li"}),"A warning is issued for each ",(0,i.mdx)("strong",{parentName:"li"},"config group file")," without a ",(0,i.mdx)("inlineCode",{parentName:"li"},"@package")," directive."),(0,i.mdx)("li",{parentName:"ul"},"In ",(0,i.mdx)("strong",{parentName:"li"},"Hydra 1.1")," the default for ",(0,i.mdx)("strong",{parentName:"li"},"config group files")," will become ",(0,i.mdx)("inlineCode",{parentName:"li"},"_group_"))),(0,i.mdx)("p",null,"By adding an explicit ",(0,i.mdx)("inlineCode",{parentName:"p"},"@package")," to your configs files, you guarantee that they",(0,i.mdx)("br",{parentName:"p"}),"\n","will not break when you upgrade to Hydra 1.1."))}s.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/39a98d83.c535e732.js b/assets/js/39a98d83.c535e732.js new file mode 100644 index 0000000000..2043ea5041 --- /dev/null +++ b/assets/js/39a98d83.c535e732.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3393],{15680:(e,a,t)=>{t.r(a),t.d(a,{MDXContext:()=>c,MDXProvider:()=>s,mdx:()=>v,useMDXComponents:()=>m,withMDXComponents:()=>p});var n=t(96540);function r(e,a,t){return a in e?Object.defineProperty(e,a,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[a]=t,e}function i(){return i=Object.assign||function(e){for(var a=1;a=0||(r[t]=e[t]);return r}(e,a);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(r[t]=e[t])}return r}var c=n.createContext({}),p=function(e){return function(a){var t=m(a.components);return n.createElement(e,i({},a,{components:t}))}},m=function(e){var a=n.useContext(c),t=a;return e&&(t="function"==typeof e?e(a):l(l({},a),e)),t},s=function(e){var a=m(e.components);return n.createElement(c.Provider,{value:a},e.children)},g={inlineCode:"code",wrapper:function(e){var a=e.children;return n.createElement(n.Fragment,{},a)}},u=n.forwardRef((function(e,a){var t=e.components,r=e.mdxType,i=e.originalType,o=e.parentName,c=d(e,["components","mdxType","originalType","parentName"]),p=m(t),s=r,u=p["".concat(o,".").concat(s)]||p[s]||g[s]||i;return t?n.createElement(u,l(l({ref:a},c),{},{components:t})):n.createElement(u,l({ref:a},c))}));function v(e,a){var t=arguments,r=a&&a.mdxType;if("string"==typeof e||r){var i=t.length,o=new Array(i);o[0]=u;var l={};for(var d in a)hasOwnProperty.call(a,d)&&(l[d]=a[d]);l.originalType=e,l.mdxType="string"==typeof e?e:r,o[1]=l;for(var c=2;c{t.r(a),t.d(a,{contentTitle:()=>d,default:()=>s,frontMatter:()=>l,metadata:()=>c,toc:()=>p});var n=t(58168),r=t(98587),i=(t(96540),t(15680)),o=["components"],l={id:"overriding_packages",title:"Overriding packages"},d=void 0,c={unversionedId:"advanced/overriding_packages",id:"version-1.0/advanced/overriding_packages",title:"Overriding packages",description:"Example application",source:"@site/versioned_docs/version-1.0/advanced/overriding_packages.md",sourceDirName:"advanced",slug:"/advanced/overriding_packages",permalink:"/docs/1.0/advanced/overriding_packages",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.0/advanced/overriding_packages.md",tags:[],version:"1.0",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"overriding_packages",title:"Overriding packages"},sidebar:"version-1.0/docs",previous:{title:"Extended Override syntax",permalink:"/docs/1.0/advanced/override_grammar/extended"},next:{title:"Config Search Path",permalink:"/docs/1.0/advanced/search_path"}},p=[{value:"Package specification",id:"package-specification",children:[],level:3},{value:"Overriding the package in a file via a package directive",id:"overriding-the-package-in-a-file-via-a-package-directive",children:[{value:"Examples",id:"examples",children:[{value:"A package directive with a literal",id:"a-package-directive-with-a-literal",children:[],level:5},{value:"A package directive with _group_ and _name_",id:"a-package-directive-with-_group_-and-_name_",children:[],level:5}],level:4}],level:3},{value:"Overriding the package via the defaults list",id:"overriding-the-package-via-the-defaults-list",children:[],level:3},{value:"History and future of the package directive",id:"history-and-future-of-the-package-directive",children:[],level:3}],m={toc:p};function s(e){var a=e.components,t=(0,r.A)(e,o);return(0,i.mdx)("wrapper",(0,n.A)({},m,t,{components:a,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,(0,i.mdx)("a",{parentName:"p",href:"https://github.com/facebookresearch/hydra/tree/1.0_branch/examples/advanced/package_overrides"},(0,i.mdx)("img",{parentName:"a",src:"https://img.shields.io/badge/-Example%20application-informational",alt:"Example application"}))),(0,i.mdx)("p",null,"The contents of a config file can be relocated, or replicated, within the config, via package overrides."),(0,i.mdx)("h3",{id:"package-specification"},"Package specification"),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Definition of a package"',title:'"Definition',of:!0,a:!0,'package"':!0},"PACKAGE : _global_ | COMPONENT[.COMPONENT]*\nCOMPONENT : _group_ | _name_ | \\w+\n\n_global_ : the top level package (equivalent to the empty string).\n_group_ : the config group in dot notation: foo/bar/zoo.yaml -> foo.bar\n_name_ : the config file name: foo/bar/zoo.yaml -> zoo\n")),(0,i.mdx)("h3",{id:"overriding-the-package-in-a-file-via-a-package-directive"},"Overriding the package in a file via a package directive"),(0,i.mdx)("p",null,"A ",(0,i.mdx)("inlineCode",{parentName:"p"},"@package directive")," specifies a common ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.0/terminology#package"},"package")," for all nodes in the config file.\nIt must be placed at the top of each ",(0,i.mdx)("inlineCode",{parentName:"p"},"config group file"),"."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Package directive examples"',title:'"Package',directive:!0,'examples"':!0},"# @package foo.bar\n# @package _global_\n# @package _group_\n# @package _group_._name_\n# @package foo._group_._name_\n")),(0,i.mdx)("h4",{id:"examples"},"Examples"),(0,i.mdx)("h5",{id:"a-package-directive-with-a-literal"},"A package directive with a literal"),(0,i.mdx)("div",{className:"row"},(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="mysql.yaml" {1-2}',title:'"mysql.yaml"',"{1-2}":!0},"# @package foo.bar\n\ndb:\n host: localhost\n port: 3306\n"))),(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Interpretation" {1-2}',title:'"Interpretation"',"{1-2}":!0},"foo:\n bar:\n db:\n host: localhost\n port: 3306\n")))),(0,i.mdx)("h5",{id:"a-package-directive-with-_group_-and-_name_"},"A package directive with ",(0,i.mdx)("inlineCode",{parentName:"h5"},"_group_")," and ",(0,i.mdx)("inlineCode",{parentName:"h5"},"_name_")),(0,i.mdx)("div",{className:"row"},(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="db/mysql.yaml" {1-2}',title:'"db/mysql.yaml"',"{1-2}":!0},"# @package _group_._name_\n\nhost: localhost\nport: 3306\n"))),(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Interpretation" {1-2}',title:'"Interpretation"',"{1-2}":!0},"db:\n mysql:\n host: localhost\n port: 3306\n")))),(0,i.mdx)("h3",{id:"overriding-the-package-via-the-defaults-list"},"Overriding the package via the defaults list"),(0,i.mdx)("p",null,"The following example adds the ",(0,i.mdx)("inlineCode",{parentName:"p"},"mysql")," config in the packages ",(0,i.mdx)("inlineCode",{parentName:"p"},"db.src")," and ",(0,i.mdx)("inlineCode",{parentName:"p"},"db.dst"),"."),(0,i.mdx)("div",{className:"row"},(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - db@db.src: mysql\n - db@db.dst: mysql\n\n\n\n\n"))),(0,i.mdx)("div",{className:"col col--6"},(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Interpretation"',title:'"Interpretation"'},"db:\n src:\n host: localhost\n port: 3306\n dst:\n host: localhost\n port: 3306\n")))),(0,i.mdx)("h3",{id:"history-and-future-of-the-package-directive"},"History and future of the package directive"),(0,i.mdx)("p",null,"The primary config, named in ",(0,i.mdx)("inlineCode",{parentName:"p"},"@hydra.main()")," should not have a package directive."),(0,i.mdx)("p",null,"For config files in config groups the default depends on the version:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"In ",(0,i.mdx)("strong",{parentName:"li"},"Hydra 0.11"),", there was an implicit default of ",(0,i.mdx)("inlineCode",{parentName:"li"},"_global_")),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"Hydra 1.0")," the default is ",(0,i.mdx)("inlineCode",{parentName:"li"},"_global_"),(0,i.mdx)("br",{parentName:"li"}),"A warning is issued for each ",(0,i.mdx)("strong",{parentName:"li"},"config group file")," without a ",(0,i.mdx)("inlineCode",{parentName:"li"},"@package")," directive."),(0,i.mdx)("li",{parentName:"ul"},"In ",(0,i.mdx)("strong",{parentName:"li"},"Hydra 1.1")," the default for ",(0,i.mdx)("strong",{parentName:"li"},"config group files")," will become ",(0,i.mdx)("inlineCode",{parentName:"li"},"_group_"))),(0,i.mdx)("p",null,"By adding an explicit ",(0,i.mdx)("inlineCode",{parentName:"p"},"@package")," to your configs files, you guarantee that they",(0,i.mdx)("br",{parentName:"p"}),"\n","will not break when you upgrade to Hydra 1.1."))}s.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/39fd50bc.488a56fc.js b/assets/js/39fd50bc.488a56fc.js new file mode 100644 index 0000000000..f87a8c45f0 --- /dev/null +++ b/assets/js/39fd50bc.488a56fc.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[8183],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>m,MDXProvider:()=>u,mdx:()=>h,useMDXComponents:()=>s,withMDXComponents:()=>d});var t=a(96540);function r(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(r[a]=e[a]);return r}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(r[a]=e[a])}return r}var m=t.createContext({}),d=function(e){return function(n){var a=s(n.components);return t.createElement(e,i({},n,{components:a}))}},s=function(e){var n=t.useContext(m),a=n;return e&&(a="function"==typeof e?e(n):p(p({},n),e)),a},u=function(e){var n=s(e.components);return t.createElement(m.Provider,{value:n},e.children)},c={inlineCode:"code",wrapper:function(e){var n=e.children;return t.createElement(t.Fragment,{},n)}},x=t.forwardRef((function(e,n){var a=e.components,r=e.mdxType,i=e.originalType,o=e.parentName,m=l(e,["components","mdxType","originalType","parentName"]),d=s(a),u=r,x=d["".concat(o,".").concat(u)]||d[u]||c[u]||i;return a?t.createElement(x,p(p({ref:n},m),{},{components:a})):t.createElement(x,p({ref:n},m))}));function h(e,n){var a=arguments,r=n&&n.mdxType;if("string"==typeof e||r){var i=a.length,o=new Array(i);o[0]=x;var p={};for(var l in n)hasOwnProperty.call(n,l)&&(p[l]=n[l]);p.originalType=e,p.mdxType="string"==typeof e?e:r,o[1]=p;for(var m=2;m{a.d(n,{A:()=>l,C:()=>m});var t=a(58168),r=a(96540),i=a(75489),o=a(44586),p=a(74098);function l(e){return r.createElement(i.default,(0,t.A)({},e,{to:(n=e.to,l=(0,p.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(a=null==l?void 0:l.name)?a:"current"]+n),target:"_blank"}));var n,a,l}function m(e){var n,a=null!=(n=e.text)?n:"Example (Click Here)";return r.createElement(l,e,r.createElement("span",null,"\xa0"),r.createElement("img",{src:"https://img.shields.io/badge/-"+a+"-informational",alt:"Example (Click Here)"}))}},12865:(e,n,a)=>{a.r(n),a.d(n,{contentTitle:()=>d,default:()=>h,frontMatter:()=>m,metadata:()=>s,toc:()=>u});var t,r=a(58168),i=a(98587),o=(a(96540),a(15680)),p=a(49595),l=["components"],m={id:"ax_sweeper",title:"Ax Sweeper plugin",sidebar_label:"Ax Sweeper plugin"},d=void 0,s={unversionedId:"plugins/ax_sweeper",id:"version-1.2/plugins/ax_sweeper",title:"Ax Sweeper plugin",description:"PyPI",source:"@site/versioned_docs/version-1.2/plugins/ax_sweeper.md",sourceDirName:"plugins",slug:"/plugins/ax_sweeper",permalink:"/docs/1.2/plugins/ax_sweeper",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/plugins/ax_sweeper.md",tags:[],version:"1.2",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"ax_sweeper",title:"Ax Sweeper plugin",sidebar_label:"Ax Sweeper plugin"},sidebar:"docs",previous:{title:"Submitit Launcher plugin",permalink:"/docs/1.2/plugins/submitit_launcher"},next:{title:"Nevergrad Sweeper plugin",permalink:"/docs/1.2/plugins/nevergrad_sweeper"}},u=[{value:"Installation",id:"installation",children:[],level:3},{value:"Usage",id:"usage",children:[],level:3}],c=(t="GithubLink",function(e){return console.warn("Component "+t+" was not imported, exported, or provided by MDXProvider as global scope"),(0,o.mdx)("div",e)}),x={toc:u};function h(e){var n=e.components,a=(0,i.A)(e,l);return(0,o.mdx)("wrapper",(0,r.A)({},x,a,{components:n,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,(0,o.mdx)("a",{parentName:"p",href:"https://img.shields.io/pypi/v/hydra-ax-sweeper"},(0,o.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/v/hydra-ax-sweeper",alt:"PyPI"})),"\n",(0,o.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/l/hydra-ax-sweeper",alt:"PyPI - License"}),"\n",(0,o.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/pyversions/hydra-ax-sweeper",alt:"PyPI - Python Version"}),"\n",(0,o.mdx)("a",{parentName:"p",href:"https://pypistats.org/packages/hydra-ax-sweeper"},(0,o.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/dm/hydra-ax-sweeper.svg",alt:"PyPI - Downloads"})),(0,o.mdx)(p.C,{text:"Example application",to:"plugins/hydra_ax_sweeper/example",mdxType:"ExampleGithubLink"}),(0,o.mdx)(p.C,{text:"Plugin source",to:"plugins/hydra_ax_sweeper",mdxType:"ExampleGithubLink"})),(0,o.mdx)("p",null,"This plugin provides a mechanism for Hydra applications to use the ",(0,o.mdx)("a",{parentName:"p",href:"https://ax.dev/"},"Adaptive Experimentation Platform, aka Ax"),". Ax can optimize any experiment - machine learning experiments, A/B tests, and simulations."),(0,o.mdx)("h3",{id:"installation"},"Installation"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-commandline"},"pip install hydra-ax-sweeper --upgrade\n")),(0,o.mdx)("h3",{id:"usage"},"Usage"),(0,o.mdx)("p",null,"Once installed, add ",(0,o.mdx)("inlineCode",{parentName:"p"},"hydra/sweeper=ax")," to your command line. Alternatively, override ",(0,o.mdx)("inlineCode",{parentName:"p"},"hydra/sweeper")," in your config:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - override hydra/sweeper: ax\n")),(0,o.mdx)("p",null,"We include an example of how to use this plugin. The file ",(0,o.mdx)(c,{to:"plugins/hydra_ax_sweeper/example/banana.py",mdxType:"GithubLink"},"example/banana.py"),"\nimplements the ",(0,o.mdx)("a",{parentName:"p",href:"https://en.wikipedia.org/wiki/Rosenbrock_function"},"Rosenbrock function (aka Banana function)"),".\nThe return value of the function should be the value that we want to optimize."),(0,o.mdx)("p",null,"To compute the best parameters for the Banana function, clone the code and run the following command in the ",(0,o.mdx)("inlineCode",{parentName:"p"},"plugins/hydra_ax_sweeper")," directory:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre"},"python example/banana.py -m 'banana.x=int(interval(-5, 5))' 'banana.y=interval(-5, 10.1)'\n")),(0,o.mdx)("p",null,"The output of a run looks like:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre"},"[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")),(0,o.mdx)("p",null,"In this example, we set the range of ",(0,o.mdx)("inlineCode",{parentName:"p"},"x")," parameter as an integer in the interval ",(0,o.mdx)("inlineCode",{parentName:"p"},"[-5, 5]")," and the range of ",(0,o.mdx)("inlineCode",{parentName:"p"},"y")," parameter as a float in the interval ",(0,o.mdx)("inlineCode",{parentName:"p"},"[-5, 10.1]"),". Note that in the case of ",(0,o.mdx)("inlineCode",{parentName:"p"},"x"),", we used ",(0,o.mdx)("inlineCode",{parentName:"p"},"int(interval(...))")," and hence only integers are sampled. In the case of ",(0,o.mdx)("inlineCode",{parentName:"p"},"y"),", we used ",(0,o.mdx)("inlineCode",{parentName:"p"},"interval(...)")," which refers to a floating-point interval. Other supported formats are fixed parameters (e.g.",(0,o.mdx)("inlineCode",{parentName:"p"}," banana.x=5.0"),"), choice parameters (eg ",(0,o.mdx)("inlineCode",{parentName:"p"},"banana.x=choice(1,2,3)"),") and range (eg ",(0,o.mdx)("inlineCode",{parentName:"p"},"banana.x=range(1, 10)"),"). Note that ",(0,o.mdx)("inlineCode",{parentName:"p"},"interval"),", ",(0,o.mdx)("inlineCode",{parentName:"p"},"choice")," etc. are functions provided by Hydra, and you can read more about them ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.2/advanced/override_grammar/extended"},"here"),". An important thing to remember is, use ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.2/advanced/override_grammar/extended#interval-sweep"},(0,o.mdx)("inlineCode",{parentName:"a"},"interval"))," when we want Ax to sample values from an interval. ",(0,o.mdx)("a",{parentName:"p",href:"https://ax.dev/api/ax.html#ax.RangeParameter"},(0,o.mdx)("inlineCode",{parentName:"a"},"RangeParameter"))," in Ax is equivalent to ",(0,o.mdx)("inlineCode",{parentName:"p"},"interval")," in Hydra. Remember to use ",(0,o.mdx)("inlineCode",{parentName:"p"},"int(interval(...))")," if you want to sample only integer points from the interval. ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.2/advanced/override_grammar/extended#range-sweep"},(0,o.mdx)("inlineCode",{parentName:"a"},"range"))," can be used as an alternate way of specifying choice parameters. For example ",(0,o.mdx)("inlineCode",{parentName:"p"},"python example/banana.py -m banana.x=choice(1, 2, 3, 4)")," is equivalent to ",(0,o.mdx)("inlineCode",{parentName:"p"},"python example/banana.py -m banana.x=range(1, 5)"),"."),(0,o.mdx)("p",null,"The values of the ",(0,o.mdx)("inlineCode",{parentName:"p"},"x")," and ",(0,o.mdx)("inlineCode",{parentName:"p"},"y")," parameters can also be set using the config file ",(0,o.mdx)("inlineCode",{parentName:"p"},"plugins/hydra_ax_sweeper/example/conf/config.yaml"),". For instance, the configuration corresponding to the commandline arguments is as follows:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre"},"banana.x:\n type: range\n bounds: [-5, 5]\n\nbanana.y:\n type: range\n bounds: [-5, 10.1]\n")),(0,o.mdx)("p",null,"To sample in log space, you can tag the commandline override with ",(0,o.mdx)("inlineCode",{parentName:"p"},"log"),". E.g. ",(0,o.mdx)("inlineCode",{parentName:"p"},"python example/banana.py -m banana.x=tag(log, interval(1, 1000))"),". You can set ",(0,o.mdx)("inlineCode",{parentName:"p"},"log_scale: true")," in the input config to achieve the same."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre"},"banana.z:\n type: range\n bounds: [1, 100]\n log_scale: true\n")),(0,o.mdx)("p",null,"In general, the plugin supports setting all the Ax supported ",(0,o.mdx)("a",{parentName:"p",href:"https://ax.dev/api/core.html?highlight=range#module-ax.core.parameter"},"Parameters")," in the config. According to the ",(0,o.mdx)("a",{parentName:"p",href:"https://ax.dev/api/service.html#ax.service.ax_client.AxClient.create_experiment"},"Ax documentation"),", the required elements in the config are:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"name")," - Name of the parameter. It is of type string."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"type")," - Type of the parameter. It can take the following values: ",(0,o.mdx)("inlineCode",{parentName:"li"},"range"),", ",(0,o.mdx)("inlineCode",{parentName:"li"},"fixed"),", or ",(0,o.mdx)("inlineCode",{parentName:"li"},"choice"),"."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"bounds")," - Required only for the ",(0,o.mdx)("inlineCode",{parentName:"li"},"range")," parameters. It should be a list of two values, with the lower bound first."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"values")," - Required only for the ",(0,o.mdx)("inlineCode",{parentName:"li"},"choice")," parameters. It should be a list of values."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"value")," - Required only for the ",(0,o.mdx)("inlineCode",{parentName:"li"},"fixed")," parameters. It should be a single value.")),(0,o.mdx)("p",null,"Note that if you want to sample integers in the range ",(0,o.mdx)("inlineCode",{parentName:"p"},"-5")," to ",(0,o.mdx)("inlineCode",{parentName:"p"},"5"),", you need to specify the range as ",(0,o.mdx)("inlineCode",{parentName:"p"},"int(interval(-5, 5))")," (in the command line) or ",(0,o.mdx)("inlineCode",{parentName:"p"},"[-5, 5]")," (in config). If you want to sample floats in range ",(0,o.mdx)("inlineCode",{parentName:"p"},"-5")," to ",(0,o.mdx)("inlineCode",{parentName:"p"},"5"),", you need to specify the range as ",(0,o.mdx)("inlineCode",{parentName:"p"},"interval(-5, 5)")," (in the command line) or ",(0,o.mdx)("inlineCode",{parentName:"p"},"[-5.0, 5.0]")," (in config)."),(0,o.mdx)("p",null,"The Ax Sweeper assumes the optimized function is a noisy function with unknown measurement uncertainty.\nThis can be changed by overriding the ",(0,o.mdx)("inlineCode",{parentName:"p"},"is_noisy")," parameter to False, which specifies that each measurement is exact, i.e., each measurement has a measurement uncertainty of zero."),(0,o.mdx)("p",null,"If measurement uncertainty is known or can be estimated (e.g., via a heuristic or via the ",(0,o.mdx)("a",{parentName:"p",href:"https://en.wikipedia.org/wiki/Standard_error"},"standard error of the mean")," of repeated measurements), the measurement function can return the tuple ",(0,o.mdx)("inlineCode",{parentName:"p"},"(measurement_value, measurement_uncertainty)")," instead of a scalar value."),(0,o.mdx)("p",null,"The 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:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python your_app.py hydra/sweeper=ax --cfg hydra -p hydra.sweeper"',title:'"$',python:!0,"your_app.py":!0,"hydra/sweeper":"ax","--cfg":!0,hydra:!0,"-p":!0,'hydra.sweeper"':!0},"# @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")),(0,o.mdx)("p",null,"There are several standard approaches for configuring plugins. Check ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.2/patterns/configuring_plugins"},"this page")," for more information."))}h.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/39fd50bc.891a2462.js b/assets/js/39fd50bc.891a2462.js deleted file mode 100644 index 0bf3831bac..0000000000 --- a/assets/js/39fd50bc.891a2462.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[8183],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>m,MDXProvider:()=>u,mdx:()=>h,useMDXComponents:()=>s,withMDXComponents:()=>d});var t=a(96540);function r(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(r[a]=e[a]);return r}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(r[a]=e[a])}return r}var m=t.createContext({}),d=function(e){return function(n){var a=s(n.components);return t.createElement(e,i({},n,{components:a}))}},s=function(e){var n=t.useContext(m),a=n;return e&&(a="function"==typeof e?e(n):p(p({},n),e)),a},u=function(e){var n=s(e.components);return t.createElement(m.Provider,{value:n},e.children)},c={inlineCode:"code",wrapper:function(e){var n=e.children;return t.createElement(t.Fragment,{},n)}},x=t.forwardRef((function(e,n){var a=e.components,r=e.mdxType,i=e.originalType,o=e.parentName,m=l(e,["components","mdxType","originalType","parentName"]),d=s(a),u=r,x=d["".concat(o,".").concat(u)]||d[u]||c[u]||i;return a?t.createElement(x,p(p({ref:n},m),{},{components:a})):t.createElement(x,p({ref:n},m))}));function h(e,n){var a=arguments,r=n&&n.mdxType;if("string"==typeof e||r){var i=a.length,o=new Array(i);o[0]=x;var p={};for(var l in n)hasOwnProperty.call(n,l)&&(p[l]=n[l]);p.originalType=e,p.mdxType="string"==typeof e?e:r,o[1]=p;for(var m=2;m{a.d(n,{A:()=>l,C:()=>m});var t=a(58168),r=a(96540),i=a(75489),o=a(44586),p=a(74098);function l(e){return r.createElement(i.default,(0,t.A)({},e,{to:(n=e.to,l=(0,p.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(a=null==l?void 0:l.name)?a:"current"]+n),target:"_blank"}));var n,a,l}function m(e){var n,a=null!=(n=e.text)?n:"Example (Click Here)";return r.createElement(l,e,r.createElement("span",null,"\xa0"),r.createElement("img",{src:"https://img.shields.io/badge/-"+a+"-informational",alt:"Example (Click Here)"}))}},12865:(e,n,a)=>{a.r(n),a.d(n,{contentTitle:()=>d,default:()=>h,frontMatter:()=>m,metadata:()=>s,toc:()=>u});var t,r=a(58168),i=a(98587),o=(a(96540),a(15680)),p=a(49595),l=["components"],m={id:"ax_sweeper",title:"Ax Sweeper plugin",sidebar_label:"Ax Sweeper plugin"},d=void 0,s={unversionedId:"plugins/ax_sweeper",id:"version-1.2/plugins/ax_sweeper",title:"Ax Sweeper plugin",description:"PyPI",source:"@site/versioned_docs/version-1.2/plugins/ax_sweeper.md",sourceDirName:"plugins",slug:"/plugins/ax_sweeper",permalink:"/docs/1.2/plugins/ax_sweeper",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.2/plugins/ax_sweeper.md",tags:[],version:"1.2",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"ax_sweeper",title:"Ax Sweeper plugin",sidebar_label:"Ax Sweeper plugin"},sidebar:"docs",previous:{title:"Submitit Launcher plugin",permalink:"/docs/1.2/plugins/submitit_launcher"},next:{title:"Nevergrad Sweeper plugin",permalink:"/docs/1.2/plugins/nevergrad_sweeper"}},u=[{value:"Installation",id:"installation",children:[],level:3},{value:"Usage",id:"usage",children:[],level:3}],c=(t="GithubLink",function(e){return console.warn("Component "+t+" was not imported, exported, or provided by MDXProvider as global scope"),(0,o.mdx)("div",e)}),x={toc:u};function h(e){var n=e.components,a=(0,i.A)(e,l);return(0,o.mdx)("wrapper",(0,r.A)({},x,a,{components:n,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,(0,o.mdx)("a",{parentName:"p",href:"https://img.shields.io/pypi/v/hydra-ax-sweeper"},(0,o.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/v/hydra-ax-sweeper",alt:"PyPI"})),"\n",(0,o.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/l/hydra-ax-sweeper",alt:"PyPI - License"}),"\n",(0,o.mdx)("img",{parentName:"p",src:"https://img.shields.io/pypi/pyversions/hydra-ax-sweeper",alt:"PyPI - Python Version"}),"\n",(0,o.mdx)("a",{parentName:"p",href:"https://pypistats.org/packages/hydra-ax-sweeper"},(0,o.mdx)("img",{parentName:"a",src:"https://img.shields.io/pypi/dm/hydra-ax-sweeper.svg",alt:"PyPI - Downloads"})),(0,o.mdx)(p.C,{text:"Example application",to:"plugins/hydra_ax_sweeper/example",mdxType:"ExampleGithubLink"}),(0,o.mdx)(p.C,{text:"Plugin source",to:"plugins/hydra_ax_sweeper",mdxType:"ExampleGithubLink"})),(0,o.mdx)("p",null,"This plugin provides a mechanism for Hydra applications to use the ",(0,o.mdx)("a",{parentName:"p",href:"https://ax.dev/"},"Adaptive Experimentation Platform, aka Ax"),". Ax can optimize any experiment - machine learning experiments, A/B tests, and simulations."),(0,o.mdx)("h3",{id:"installation"},"Installation"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-commandline"},"pip install hydra-ax-sweeper --upgrade\n")),(0,o.mdx)("h3",{id:"usage"},"Usage"),(0,o.mdx)("p",null,"Once installed, add ",(0,o.mdx)("inlineCode",{parentName:"p"},"hydra/sweeper=ax")," to your command line. Alternatively, override ",(0,o.mdx)("inlineCode",{parentName:"p"},"hydra/sweeper")," in your config:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"defaults:\n - override hydra/sweeper: ax\n")),(0,o.mdx)("p",null,"We include an example of how to use this plugin. The file ",(0,o.mdx)(c,{to:"plugins/hydra_ax_sweeper/example/banana.py",mdxType:"GithubLink"},"example/banana.py"),"\nimplements the ",(0,o.mdx)("a",{parentName:"p",href:"https://en.wikipedia.org/wiki/Rosenbrock_function"},"Rosenbrock function (aka Banana function)"),".\nThe return value of the function should be the value that we want to optimize."),(0,o.mdx)("p",null,"To compute the best parameters for the Banana function, clone the code and run the following command in the ",(0,o.mdx)("inlineCode",{parentName:"p"},"plugins/hydra_ax_sweeper")," directory:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre"},"python example/banana.py -m 'banana.x=int(interval(-5, 5))' 'banana.y=interval(-5, 10.1)'\n")),(0,o.mdx)("p",null,"The output of a run looks like:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre"},"[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")),(0,o.mdx)("p",null,"In this example, we set the range of ",(0,o.mdx)("inlineCode",{parentName:"p"},"x")," parameter as an integer in the interval ",(0,o.mdx)("inlineCode",{parentName:"p"},"[-5, 5]")," and the range of ",(0,o.mdx)("inlineCode",{parentName:"p"},"y")," parameter as a float in the interval ",(0,o.mdx)("inlineCode",{parentName:"p"},"[-5, 10.1]"),". Note that in the case of ",(0,o.mdx)("inlineCode",{parentName:"p"},"x"),", we used ",(0,o.mdx)("inlineCode",{parentName:"p"},"int(interval(...))")," and hence only integers are sampled. In the case of ",(0,o.mdx)("inlineCode",{parentName:"p"},"y"),", we used ",(0,o.mdx)("inlineCode",{parentName:"p"},"interval(...)")," which refers to a floating-point interval. Other supported formats are fixed parameters (e.g.",(0,o.mdx)("inlineCode",{parentName:"p"}," banana.x=5.0"),"), choice parameters (eg ",(0,o.mdx)("inlineCode",{parentName:"p"},"banana.x=choice(1,2,3)"),") and range (eg ",(0,o.mdx)("inlineCode",{parentName:"p"},"banana.x=range(1, 10)"),"). Note that ",(0,o.mdx)("inlineCode",{parentName:"p"},"interval"),", ",(0,o.mdx)("inlineCode",{parentName:"p"},"choice")," etc. are functions provided by Hydra, and you can read more about them ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.2/advanced/override_grammar/extended"},"here"),". An important thing to remember is, use ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.2/advanced/override_grammar/extended#interval-sweep"},(0,o.mdx)("inlineCode",{parentName:"a"},"interval"))," when we want Ax to sample values from an interval. ",(0,o.mdx)("a",{parentName:"p",href:"https://ax.dev/api/ax.html#ax.RangeParameter"},(0,o.mdx)("inlineCode",{parentName:"a"},"RangeParameter"))," in Ax is equivalent to ",(0,o.mdx)("inlineCode",{parentName:"p"},"interval")," in Hydra. Remember to use ",(0,o.mdx)("inlineCode",{parentName:"p"},"int(interval(...))")," if you want to sample only integer points from the interval. ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.2/advanced/override_grammar/extended#range-sweep"},(0,o.mdx)("inlineCode",{parentName:"a"},"range"))," can be used as an alternate way of specifying choice parameters. For example ",(0,o.mdx)("inlineCode",{parentName:"p"},"python example/banana.py -m banana.x=choice(1, 2, 3, 4)")," is equivalent to ",(0,o.mdx)("inlineCode",{parentName:"p"},"python example/banana.py -m banana.x=range(1, 5)"),"."),(0,o.mdx)("p",null,"The values of the ",(0,o.mdx)("inlineCode",{parentName:"p"},"x")," and ",(0,o.mdx)("inlineCode",{parentName:"p"},"y")," parameters can also be set using the config file ",(0,o.mdx)("inlineCode",{parentName:"p"},"plugins/hydra_ax_sweeper/example/conf/config.yaml"),". For instance, the configuration corresponding to the commandline arguments is as follows:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre"},"banana.x:\n type: range\n bounds: [-5, 5]\n\nbanana.y:\n type: range\n bounds: [-5, 10.1]\n")),(0,o.mdx)("p",null,"To sample in log space, you can tag the commandline override with ",(0,o.mdx)("inlineCode",{parentName:"p"},"log"),". E.g. ",(0,o.mdx)("inlineCode",{parentName:"p"},"python example/banana.py -m banana.x=tag(log, interval(1, 1000))"),". You can set ",(0,o.mdx)("inlineCode",{parentName:"p"},"log_scale: true")," in the input config to achieve the same."),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre"},"banana.z:\n type: range\n bounds: [1, 100]\n log_scale: true\n")),(0,o.mdx)("p",null,"In general, the plugin supports setting all the Ax supported ",(0,o.mdx)("a",{parentName:"p",href:"https://ax.dev/api/core.html?highlight=range#module-ax.core.parameter"},"Parameters")," in the config. According to the ",(0,o.mdx)("a",{parentName:"p",href:"https://ax.dev/api/service.html#ax.service.ax_client.AxClient.create_experiment"},"Ax documentation"),", the required elements in the config are:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"name")," - Name of the parameter. It is of type string."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"type")," - Type of the parameter. It can take the following values: ",(0,o.mdx)("inlineCode",{parentName:"li"},"range"),", ",(0,o.mdx)("inlineCode",{parentName:"li"},"fixed"),", or ",(0,o.mdx)("inlineCode",{parentName:"li"},"choice"),"."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"bounds")," - Required only for the ",(0,o.mdx)("inlineCode",{parentName:"li"},"range")," parameters. It should be a list of two values, with the lower bound first."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"values")," - Required only for the ",(0,o.mdx)("inlineCode",{parentName:"li"},"choice")," parameters. It should be a list of values."),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"value")," - Required only for the ",(0,o.mdx)("inlineCode",{parentName:"li"},"fixed")," parameters. It should be a single value.")),(0,o.mdx)("p",null,"Note that if you want to sample integers in the range ",(0,o.mdx)("inlineCode",{parentName:"p"},"-5")," to ",(0,o.mdx)("inlineCode",{parentName:"p"},"5"),", you need to specify the range as ",(0,o.mdx)("inlineCode",{parentName:"p"},"int(interval(-5, 5))")," (in the command line) or ",(0,o.mdx)("inlineCode",{parentName:"p"},"[-5, 5]")," (in config). If you want to sample floats in range ",(0,o.mdx)("inlineCode",{parentName:"p"},"-5")," to ",(0,o.mdx)("inlineCode",{parentName:"p"},"5"),", you need to specify the range as ",(0,o.mdx)("inlineCode",{parentName:"p"},"interval(-5, 5)")," (in the command line) or ",(0,o.mdx)("inlineCode",{parentName:"p"},"[-5.0, 5.0]")," (in config)."),(0,o.mdx)("p",null,"The Ax Sweeper assumes the optimized function is a noisy function with unknown measurement uncertainty.\nThis can be changed by overriding the ",(0,o.mdx)("inlineCode",{parentName:"p"},"is_noisy")," parameter to False, which specifies that each measurement is exact, i.e., each measurement has a measurement uncertainty of zero."),(0,o.mdx)("p",null,"If measurement uncertainty is known or can be estimated (e.g., via a heuristic or via the ",(0,o.mdx)("a",{parentName:"p",href:"https://en.wikipedia.org/wiki/Standard_error"},"standard error of the mean")," of repeated measurements), the measurement function can return the tuple ",(0,o.mdx)("inlineCode",{parentName:"p"},"(measurement_value, measurement_uncertainty)")," instead of a scalar value."),(0,o.mdx)("p",null,"The 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:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="$ python your_app.py hydra/sweeper=ax --cfg hydra -p hydra.sweeper"',title:'"$',python:!0,"your_app.py":!0,"hydra/sweeper":"ax","--cfg":!0,hydra:!0,"-p":!0,'hydra.sweeper"':!0},"# @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")),(0,o.mdx)("p",null,"There are several standard approaches for configuring plugins. Check ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.2/patterns/configuring_plugins"},"this page")," for more information."))}h.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/3ab89cf6.3d3704c2.js b/assets/js/3ab89cf6.3d3704c2.js deleted file mode 100644 index 949a122980..0000000000 --- a/assets/js/3ab89cf6.3d3704c2.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3525],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>l,MDXProvider:()=>u,mdx:()=>g,useMDXComponents:()=>d,withMDXComponents:()=>p});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var l=r.createContext({}),p=function(e){return function(t){var n=d(t.components);return r.createElement(e,a({},t,{components:n}))}},d=function(e){var t=r.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):s(s({},t),e)),n},u=function(e){var t=d(e.components);return r.createElement(l.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},f=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,l=c(e,["components","mdxType","originalType","parentName"]),p=d(n),u=o,f=p["".concat(i,".").concat(u)]||p[u]||m[u]||a;return n?r.createElement(f,s(s({ref:t},l),{},{components:n})):r.createElement(f,s({ref:t},l))}));function g(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=n.length,i=new Array(a);i[0]=f;var s={};for(var c in t)hasOwnProperty.call(t,c)&&(s[c]=t[c]);s.originalType=e,s.mdxType="string"==typeof e?e:o,i[1]=s;for(var l=2;l{n.d(t,{A:()=>c,C:()=>l});var r=n(58168),o=n(96540),a=n(75489),i=n(44586),s=n(74098);function c(e){return o.createElement(a.default,(0,r.A)({},e,{to:(t=e.to,c=(0,s.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==c?void 0:c.name)?n:"current"]+t),target:"_blank"}));var t,n,c}function l(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return o.createElement(c,e,o.createElement("span",null,"\xa0"),o.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},2967:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>l,default:()=>m,frontMatter:()=>c,metadata:()=>p,toc:()=>d});var r=n(58168),o=n(98587),a=(n(96540),n(15680)),i=n(49595),s=["components"],c={id:"structured_config",title:"Structured Configs example",sidebar_label:"Structured Configs example"},l=void 0,p={unversionedId:"advanced/instantiate_objects/structured_config",id:"advanced/instantiate_objects/structured_config",title:"Structured Configs example",description:"This example demonstrates the use of Structured Configs to instantiated objects.",source:"@site/docs/advanced/instantiate_objects/structured_config.md",sourceDirName:"advanced/instantiate_objects",slug:"/advanced/instantiate_objects/structured_config",permalink:"/docs/advanced/instantiate_objects/structured_config",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/advanced/instantiate_objects/structured_config.md",tags:[],version:"current",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"structured_config",title:"Structured Configs example",sidebar_label:"Structured Configs example"},sidebar:"docs",previous:{title:"Config files example",permalink:"/docs/advanced/instantiate_objects/config_files"},next:{title:"Compose API",permalink:"/docs/advanced/compose_api"}},d=[{value:"Example usage",id:"example-usage",children:[],level:4},{value:"Sample Output",id:"sample-output",children:[],level:4}],u={toc:d};function m(e){var t=e.components,n=(0,o.A)(e,s);return(0,a.mdx)("wrapper",(0,r.A)({},u,n,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)(i.C,{text:"Example applications",to:"examples/instantiate",mdxType:"ExampleGithubLink"}),(0,a.mdx)("p",null,"This example demonstrates the use of Structured Configs to instantiated objects."),(0,a.mdx)("h4",{id:"example-usage"},"Example usage"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app.py"',title:'"my_app.py"'},'class DBConnection:\n def __init__(self, driver: str, host: str, port: int) -> None:\n self.driver = driver\n self.host = host\n self.port = port\n\n def connect(self) -> None:\n print(f"{self.driver} connecting to {self.host}")\n\nclass MySQLConnection(DBConnection):\n def __init__(self, driver: str, host: str, port: int) -> None:\n super().__init__(driver=driver, host=host, port=port)\n\nclass PostgreSQLConnection(DBConnection):\n def __init__(self, driver: str, host: str, port: int, timeout: int) -> None:\n super().__init__(driver=driver, host=host, port=port)\n self.timeout = timeout\n\n@dataclass\nclass DBConfig:\n driver: str = MISSING\n host: str = "localhost"\n port: int = 80\n\n@dataclass\nclass MySQLConfig(DBConfig):\n _target_: str = "my_app.MySQLConnection"\n driver: str = "MySQL"\n port: int = 1234\n\n@dataclass\nclass PostGreSQLConfig(DBConfig):\n _target_: str = "my_app.PostgreSQLConnection"\n driver: str = "PostgreSQL"\n port: int = 5678\n timeout: int = 10\n\n@dataclass\nclass Config:\n defaults: List[Any] = field(default_factory=lambda: [{"db": "mysql"}])\n db: DBConfig = MISSING\n\n\ncs = ConfigStore.instance()\ncs.store(name="config", node=Config)\ncs.store(group="db", name="mysql", node=MySQLConfig)\ncs.store(group="db", name="postgresql", node=PostGreSQLConfig)\n\n@hydra.main(version_base=None, config_name="config")\ndef my_app(cfg: Config) -> None:\n connection = instantiate(cfg.db)\n connection.connect()\n\nif __name__ == "__main__":\n my_app()\n')),(0,a.mdx)("h4",{id:"sample-output"},"Sample Output"),(0,a.mdx)("div",{className:"row"},(0,a.mdx)("div",{className:"col col--6"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-bash"},"$ python my_app.py\nMySQL connecting to localhost:1234\n"))),(0,a.mdx)("div",{className:"col col--6"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-bash"},"$ python my_app.py db=postgresql\nPostgreSQL connecting to localhost:5678\n")))))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/3ab89cf6.6395f8d2.js b/assets/js/3ab89cf6.6395f8d2.js new file mode 100644 index 0000000000..4e65882c7c --- /dev/null +++ b/assets/js/3ab89cf6.6395f8d2.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3525],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>l,MDXProvider:()=>u,mdx:()=>g,useMDXComponents:()=>p,withMDXComponents:()=>d});var r=n(96540);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(){return a=Object.assign||function(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var l=r.createContext({}),d=function(e){return function(t){var n=p(t.components);return r.createElement(e,a({},t,{components:n}))}},p=function(e){var t=r.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):s(s({},t),e)),n},u=function(e){var t=p(e.components);return r.createElement(l.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},f=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,a=e.originalType,i=e.parentName,l=c(e,["components","mdxType","originalType","parentName"]),d=p(n),u=o,f=d["".concat(i,".").concat(u)]||d[u]||m[u]||a;return n?r.createElement(f,s(s({ref:t},l),{},{components:n})):r.createElement(f,s({ref:t},l))}));function g(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=n.length,i=new Array(a);i[0]=f;var s={};for(var c in t)hasOwnProperty.call(t,c)&&(s[c]=t[c]);s.originalType=e,s.mdxType="string"==typeof e?e:o,i[1]=s;for(var l=2;l{n.d(t,{A:()=>c,C:()=>l});var r=n(58168),o=n(96540),a=n(75489),i=n(44586),s=n(74098);function c(e){return o.createElement(a.default,(0,r.A)({},e,{to:(t=e.to,c=(0,s.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==c?void 0:c.name)?n:"current"]+t),target:"_blank"}));var t,n,c}function l(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return o.createElement(c,e,o.createElement("span",null,"\xa0"),o.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},2967:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>l,default:()=>m,frontMatter:()=>c,metadata:()=>d,toc:()=>p});var r=n(58168),o=n(98587),a=(n(96540),n(15680)),i=n(49595),s=["components"],c={id:"structured_config",title:"Structured Configs example",sidebar_label:"Structured Configs example"},l=void 0,d={unversionedId:"advanced/instantiate_objects/structured_config",id:"advanced/instantiate_objects/structured_config",title:"Structured Configs example",description:"This example demonstrates the use of Structured Configs to instantiated objects.",source:"@site/docs/advanced/instantiate_objects/structured_config.md",sourceDirName:"advanced/instantiate_objects",slug:"/advanced/instantiate_objects/structured_config",permalink:"/docs/advanced/instantiate_objects/structured_config",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/docs/advanced/instantiate_objects/structured_config.md",tags:[],version:"current",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"structured_config",title:"Structured Configs example",sidebar_label:"Structured Configs example"},sidebar:"docs",previous:{title:"Config files example",permalink:"/docs/advanced/instantiate_objects/config_files"},next:{title:"Compose API",permalink:"/docs/advanced/compose_api"}},p=[{value:"Example usage",id:"example-usage",children:[],level:4},{value:"Sample Output",id:"sample-output",children:[],level:4}],u={toc:p};function m(e){var t=e.components,n=(0,o.A)(e,s);return(0,a.mdx)("wrapper",(0,r.A)({},u,n,{components:t,mdxType:"MDXLayout"}),(0,a.mdx)(i.C,{text:"Example applications",to:"examples/instantiate",mdxType:"ExampleGithubLink"}),(0,a.mdx)("p",null,"This example demonstrates the use of Structured Configs to instantiated objects."),(0,a.mdx)("h4",{id:"example-usage"},"Example usage"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app.py"',title:'"my_app.py"'},'class DBConnection:\n def __init__(self, driver: str, host: str, port: int) -> None:\n self.driver = driver\n self.host = host\n self.port = port\n\n def connect(self) -> None:\n print(f"{self.driver} connecting to {self.host}")\n\nclass MySQLConnection(DBConnection):\n def __init__(self, driver: str, host: str, port: int) -> None:\n super().__init__(driver=driver, host=host, port=port)\n\nclass PostgreSQLConnection(DBConnection):\n def __init__(self, driver: str, host: str, port: int, timeout: int) -> None:\n super().__init__(driver=driver, host=host, port=port)\n self.timeout = timeout\n\n@dataclass\nclass DBConfig:\n driver: str = MISSING\n host: str = "localhost"\n port: int = 80\n\n@dataclass\nclass MySQLConfig(DBConfig):\n _target_: str = "my_app.MySQLConnection"\n driver: str = "MySQL"\n port: int = 1234\n\n@dataclass\nclass PostGreSQLConfig(DBConfig):\n _target_: str = "my_app.PostgreSQLConnection"\n driver: str = "PostgreSQL"\n port: int = 5678\n timeout: int = 10\n\n@dataclass\nclass Config:\n defaults: List[Any] = field(default_factory=lambda: [{"db": "mysql"}])\n db: DBConfig = MISSING\n\n\ncs = ConfigStore.instance()\ncs.store(name="config", node=Config)\ncs.store(group="db", name="mysql", node=MySQLConfig)\ncs.store(group="db", name="postgresql", node=PostGreSQLConfig)\n\n@hydra.main(version_base=None, config_name="config")\ndef my_app(cfg: Config) -> None:\n connection = instantiate(cfg.db)\n connection.connect()\n\nif __name__ == "__main__":\n my_app()\n')),(0,a.mdx)("h4",{id:"sample-output"},"Sample Output"),(0,a.mdx)("div",{className:"row"},(0,a.mdx)("div",{className:"col col--6"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-bash"},"$ python my_app.py\nMySQL connecting to localhost:1234\n"))),(0,a.mdx)("div",{className:"col col--6"},(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-bash"},"$ python my_app.py db=postgresql\nPostgreSQL connecting to localhost:5678\n")))))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/3cf33e0d.39a21c8e.js b/assets/js/3cf33e0d.39a21c8e.js deleted file mode 100644 index f79aec7aff..0000000000 --- a/assets/js/3cf33e0d.39a21c8e.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[4356],{15680:(e,n,r)=>{r.r(n),r.d(n,{MDXContext:()=>s,MDXProvider:()=>u,mdx:()=>y,useMDXComponents:()=>d,withMDXComponents:()=>c});var t=r(96540);function o(e,n,r){return n in e?Object.defineProperty(e,n,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[n]=r,e}function a(){return a=Object.assign||function(e){for(var n=1;n=0||(o[r]=e[r]);return o}(e,n);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(o[r]=e[r])}return o}var s=t.createContext({}),c=function(e){return function(n){var r=d(n.components);return t.createElement(e,a({},n,{components:r}))}},d=function(e){var n=t.useContext(s),r=n;return e&&(r="function"==typeof e?e(n):i(i({},n),e)),r},u=function(e){var n=d(e.components);return t.createElement(s.Provider,{value:n},e.children)},m={inlineCode:"code",wrapper:function(e){var n=e.children;return t.createElement(t.Fragment,{},n)}},h=t.forwardRef((function(e,n){var r=e.components,o=e.mdxType,a=e.originalType,p=e.parentName,s=l(e,["components","mdxType","originalType","parentName"]),c=d(r),u=o,h=c["".concat(p,".").concat(u)]||c[u]||m[u]||a;return r?t.createElement(h,i(i({ref:n},s),{},{components:r})):t.createElement(h,i({ref:n},s))}));function y(e,n){var r=arguments,o=n&&n.mdxType;if("string"==typeof e||o){var a=r.length,p=new Array(a);p[0]=h;var i={};for(var l in n)hasOwnProperty.call(n,l)&&(i[l]=n[l]);i.originalType=e,i.mdxType="string"==typeof e?e:o,p[1]=i;for(var s=2;s{r.r(n),r.d(n,{contentTitle:()=>l,default:()=>u,frontMatter:()=>i,metadata:()=>s,toc:()=>c});var t=r(58168),o=r(98587),a=(r(96540),r(15680)),p=["components"],i={id:"app_help",title:"Customizing Application's help",sidebar_label:"Customizing Application's help"},l=void 0,s={unversionedId:"configure_hydra/app_help",id:"version-1.0/configure_hydra/app_help",title:"Customizing Application's help",description:"Example application",source:"@site/versioned_docs/version-1.0/configure_hydra/app_help.md",sourceDirName:"configure_hydra",slug:"/configure_hydra/app_help",permalink:"/docs/1.0/configure_hydra/app_help",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.0/configure_hydra/app_help.md",tags:[],version:"1.0",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"app_help",title:"Customizing Application's help",sidebar_label:"Customizing Application's help"},sidebar:"version-1.0/docs",previous:{title:"Customizing working directory pattern",permalink:"/docs/1.0/configure_hydra/workdir"},next:{title:"Colorlog plugin",permalink:"/docs/1.0/plugins/colorlog"}},c=[],d={toc:c};function u(e){var n=e.components,r=(0,o.A)(e,p);return(0,a.mdx)("wrapper",(0,t.A)({},d,r,{components:n,mdxType:"MDXLayout"}),(0,a.mdx)("p",null,(0,a.mdx)("a",{parentName:"p",href:"https://github.com/facebookresearch/hydra/tree/1.0_branch/examples/configure_hydra/custom_help"},(0,a.mdx)("img",{parentName:"a",src:"https://img.shields.io/badge/-Example%20application-informational",alt:"Example application"}))),(0,a.mdx)("p",null,"Hydra provides two different help options:"),(0,a.mdx)("ul",null,(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"--help")," : Application specific help"),(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"--hydra-help")," Hydra specific help. ")),(0,a.mdx)("p",null,"Example output of ",(0,a.mdx)("inlineCode",{parentName:"p"},"--help"),":"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text"},"$ python my_app.py --help\n== AwesomeApp ==\n\nThis is AwesomeApp!\nYou can choose a db driver by appending\n== Configuration groups ==\nCompose your configuration from those groups (db=mysql)\n\ndb: mysql, postgresql\n\n\n== Config ==\nThis is the config generated for this run.\nYou can override everything, for example:\npython my_app.py db.user=foo db.pass=bar\n-------\ndb:\n driver: mysql\n user: omry\n pass: secret\n\n-------\n\nPowered by Hydra (https://hydra.cc)\nUse --hydra-help to view Hydra specific help\n")),(0,a.mdx)("p",null,"This output is generated from the following config group option (selected in ",(0,a.mdx)("inlineCode",{parentName:"p"},"config.yaml")," to be used by default): "),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="hydra/help/my_app_help.yaml"',title:'"hydra/help/my_app_help.yaml"'},"# @package _group_\n\n# App name, override to match the name your app is known by\napp_name: AwesomeApp\n\n# Help header, customize to describe your app to your users\nheader: == ${hydra.help.app_name} ==\n\nfooter: |-\n Powered by Hydra (https://hydra.cc)\n Use --hydra-help to view Hydra specific help\n\n# Basic Hydra flags:\n# $FLAGS_HELP\n#\n# Config groups, choose one of:\n# $APP_CONFIG_GROUPS: All config groups that does not start with hydra/.\n# $HYDRA_CONFIG_GROUPS: All the Hydra config groups (starts with hydra/)\n#\n# Configuration generated with overrides:\n# $CONFIG : Generated config\n#\ntemplate: |-\n ${hydra.help.header}\n\n This is ${hydra.help.app_name}!\n You can choose a db driver by appending\n == Configuration groups ==\n Compose your configuration from those groups (db=mysql)\n\n $APP_CONFIG_GROUPS\n\n == Config ==\n This is the config generated for this run.\n You can override everything, for example:\n python my_app.py db.user=foo db.pass=bar\n -------\n $CONFIG\n -------\n \n ${hydra.help.footer}\n")))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/3cf33e0d.5e38314b.js b/assets/js/3cf33e0d.5e38314b.js new file mode 100644 index 0000000000..d7828a21cc --- /dev/null +++ b/assets/js/3cf33e0d.5e38314b.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[4356],{15680:(e,n,r)=>{r.r(n),r.d(n,{MDXContext:()=>s,MDXProvider:()=>u,mdx:()=>y,useMDXComponents:()=>d,withMDXComponents:()=>c});var t=r(96540);function o(e,n,r){return n in e?Object.defineProperty(e,n,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[n]=r,e}function a(){return a=Object.assign||function(e){for(var n=1;n=0||(o[r]=e[r]);return o}(e,n);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(t=0;t=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(o[r]=e[r])}return o}var s=t.createContext({}),c=function(e){return function(n){var r=d(n.components);return t.createElement(e,a({},n,{components:r}))}},d=function(e){var n=t.useContext(s),r=n;return e&&(r="function"==typeof e?e(n):i(i({},n),e)),r},u=function(e){var n=d(e.components);return t.createElement(s.Provider,{value:n},e.children)},m={inlineCode:"code",wrapper:function(e){var n=e.children;return t.createElement(t.Fragment,{},n)}},h=t.forwardRef((function(e,n){var r=e.components,o=e.mdxType,a=e.originalType,p=e.parentName,s=l(e,["components","mdxType","originalType","parentName"]),c=d(r),u=o,h=c["".concat(p,".").concat(u)]||c[u]||m[u]||a;return r?t.createElement(h,i(i({ref:n},s),{},{components:r})):t.createElement(h,i({ref:n},s))}));function y(e,n){var r=arguments,o=n&&n.mdxType;if("string"==typeof e||o){var a=r.length,p=new Array(a);p[0]=h;var i={};for(var l in n)hasOwnProperty.call(n,l)&&(i[l]=n[l]);i.originalType=e,i.mdxType="string"==typeof e?e:o,p[1]=i;for(var s=2;s{r.r(n),r.d(n,{contentTitle:()=>l,default:()=>u,frontMatter:()=>i,metadata:()=>s,toc:()=>c});var t=r(58168),o=r(98587),a=(r(96540),r(15680)),p=["components"],i={id:"app_help",title:"Customizing Application's help",sidebar_label:"Customizing Application's help"},l=void 0,s={unversionedId:"configure_hydra/app_help",id:"version-1.0/configure_hydra/app_help",title:"Customizing Application's help",description:"Example application",source:"@site/versioned_docs/version-1.0/configure_hydra/app_help.md",sourceDirName:"configure_hydra",slug:"/configure_hydra/app_help",permalink:"/docs/1.0/configure_hydra/app_help",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.0/configure_hydra/app_help.md",tags:[],version:"1.0",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"app_help",title:"Customizing Application's help",sidebar_label:"Customizing Application's help"},sidebar:"version-1.0/docs",previous:{title:"Customizing working directory pattern",permalink:"/docs/1.0/configure_hydra/workdir"},next:{title:"Colorlog plugin",permalink:"/docs/1.0/plugins/colorlog"}},c=[],d={toc:c};function u(e){var n=e.components,r=(0,o.A)(e,p);return(0,a.mdx)("wrapper",(0,t.A)({},d,r,{components:n,mdxType:"MDXLayout"}),(0,a.mdx)("p",null,(0,a.mdx)("a",{parentName:"p",href:"https://github.com/facebookresearch/hydra/tree/1.0_branch/examples/configure_hydra/custom_help"},(0,a.mdx)("img",{parentName:"a",src:"https://img.shields.io/badge/-Example%20application-informational",alt:"Example application"}))),(0,a.mdx)("p",null,"Hydra provides two different help options:"),(0,a.mdx)("ul",null,(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"--help")," : Application specific help"),(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"--hydra-help")," Hydra specific help. ")),(0,a.mdx)("p",null,"Example output of ",(0,a.mdx)("inlineCode",{parentName:"p"},"--help"),":"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-text"},"$ python my_app.py --help\n== AwesomeApp ==\n\nThis is AwesomeApp!\nYou can choose a db driver by appending\n== Configuration groups ==\nCompose your configuration from those groups (db=mysql)\n\ndb: mysql, postgresql\n\n\n== Config ==\nThis is the config generated for this run.\nYou can override everything, for example:\npython my_app.py db.user=foo db.pass=bar\n-------\ndb:\n driver: mysql\n user: omry\n pass: secret\n\n-------\n\nPowered by Hydra (https://hydra.cc)\nUse --hydra-help to view Hydra specific help\n")),(0,a.mdx)("p",null,"This output is generated from the following config group option (selected in ",(0,a.mdx)("inlineCode",{parentName:"p"},"config.yaml")," to be used by default): "),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="hydra/help/my_app_help.yaml"',title:'"hydra/help/my_app_help.yaml"'},"# @package _group_\n\n# App name, override to match the name your app is known by\napp_name: AwesomeApp\n\n# Help header, customize to describe your app to your users\nheader: == ${hydra.help.app_name} ==\n\nfooter: |-\n Powered by Hydra (https://hydra.cc)\n Use --hydra-help to view Hydra specific help\n\n# Basic Hydra flags:\n# $FLAGS_HELP\n#\n# Config groups, choose one of:\n# $APP_CONFIG_GROUPS: All config groups that does not start with hydra/.\n# $HYDRA_CONFIG_GROUPS: All the Hydra config groups (starts with hydra/)\n#\n# Configuration generated with overrides:\n# $CONFIG : Generated config\n#\ntemplate: |-\n ${hydra.help.header}\n\n This is ${hydra.help.app_name}!\n You can choose a db driver by appending\n == Configuration groups ==\n Compose your configuration from those groups (db=mysql)\n\n $APP_CONFIG_GROUPS\n\n == Config ==\n This is the config generated for this run.\n You can override everything, for example:\n python my_app.py db.user=foo db.pass=bar\n -------\n $CONFIG\n -------\n \n ${hydra.help.footer}\n")))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/3d066543.0e4a2f2f.js b/assets/js/3d066543.0e4a2f2f.js new file mode 100644 index 0000000000..69a35c3c0d --- /dev/null +++ b/assets/js/3d066543.0e4a2f2f.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[6048],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>p,MDXProvider:()=>d,mdx:()=>y,useMDXComponents:()=>c,withMDXComponents:()=>m});var r=n(96540);function a(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(){return i=Object.assign||function(e){for(var t=1;t=0||(a[n]=e[n]);return a}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(a[n]=e[n])}return a}var p=r.createContext({}),m=function(e){return function(t){var n=c(t.components);return r.createElement(e,i({},t,{components:n}))}},c=function(e){var t=r.useContext(p),n=t;return e&&(n="function"==typeof e?e(t):s(s({},t),e)),n},d=function(e){var t=c(e.components);return r.createElement(p.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},f=r.forwardRef((function(e,t){var n=e.components,a=e.mdxType,i=e.originalType,o=e.parentName,p=l(e,["components","mdxType","originalType","parentName"]),m=c(n),d=a,f=m["".concat(o,".").concat(d)]||m[d]||u[d]||i;return n?r.createElement(f,s(s({ref:t},p),{},{components:n})):r.createElement(f,s({ref:t},p))}));function y(e,t){var n=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var i=n.length,o=new Array(i);o[0]=f;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s.mdxType="string"==typeof e?e:a,o[1]=s;for(var p=2;p{n.d(t,{A:()=>l,C:()=>p});var r=n(58168),a=n(96540),i=n(75489),o=n(44586),s=n(74098);function l(e){return a.createElement(i.default,(0,r.A)({},e,{to:(t=e.to,l=(0,s.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==l?void 0:l.name)?n:"current"]+t),target:"_blank"}));var t,n,l}function p(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return a.createElement(l,e,a.createElement("span",null,"\xa0"),a.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},2355:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>p,default:()=>u,frontMatter:()=>l,metadata:()=>m,toc:()=>c});var r=n(58168),a=n(98587),i=(n(96540),n(15680)),o=n(49595),s=["components"],l={id:"simple_cli",title:"A simple command-line application"},p=void 0,m={unversionedId:"tutorials/basic/your_first_app/simple_cli",id:"version-1.3/tutorials/basic/your_first_app/simple_cli",title:"A simple command-line application",description:"This is a simple Hydra application that prints your configuration.",source:"@site/versioned_docs/version-1.3/tutorials/basic/your_first_app/1_simple_cli.md",sourceDirName:"tutorials/basic/your_first_app",slug:"/tutorials/basic/your_first_app/simple_cli",permalink:"/docs/1.3/tutorials/basic/your_first_app/simple_cli",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/tutorials/basic/your_first_app/1_simple_cli.md",tags:[],version:"1.3",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:1,frontMatter:{id:"simple_cli",title:"A simple command-line application"},sidebar:"docs",previous:{title:"Tutorials intro",permalink:"/docs/1.3/tutorials/intro"},next:{title:"Specifying a config file",permalink:"/docs/1.3/tutorials/basic/your_first_app/config_file"}},c=[],d={toc:c};function u(e){var t=e.components,n=(0,a.A)(e,s);return(0,i.mdx)("wrapper",(0,r.A)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,i.mdx)(o.C,{to:"examples/tutorials/basic/your_first_hydra_app/1_simple_cli/my_app.py",mdxType:"ExampleGithubLink"}),(0,i.mdx)("p",null,"This is a simple Hydra application that prints your configuration.\nThe ",(0,i.mdx)("inlineCode",{parentName:"p"},"my_app")," function is a placeholder for your code.\nWe will slowly evolve this example to showcase more Hydra features."),(0,i.mdx)("p",null,"The examples in this tutorial are available ",(0,i.mdx)(o.A,{to:"examples/tutorials/basic",mdxType:"GithubLink"},"here"),"."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app.py"',title:'"my_app.py"'},'from omegaconf import DictConfig, OmegaConf\nimport hydra\n\n@hydra.main(version_base=None)\ndef my_app(cfg: DictConfig) -> None:\n print(OmegaConf.to_yaml(cfg))\n\nif __name__ == "__main__":\n my_app()\n')),(0,i.mdx)("p",null,"In this example, Hydra creates an empty ",(0,i.mdx)("inlineCode",{parentName:"p"},"cfg")," object and passes it to the function annotated with ",(0,i.mdx)("inlineCode",{parentName:"p"},"@hydra.main"),"."),(0,i.mdx)("p",null,"You can add config values via the command line. The ",(0,i.mdx)("inlineCode",{parentName:"p"},"+")," indicates that the field is new."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py +db.driver=mysql +db.user=omry +db.password=secret\ndb:\n driver: mysql\n user: omry\n password: secret\n")),(0,i.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,i.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,i.mdx)("h5",{parentName:"div"},(0,i.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,i.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,i.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"info")),(0,i.mdx)("div",{parentName:"div",className:"admonition-content"},(0,i.mdx)("p",{parentName:"div"},"See the ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.3/upgrades/version_base"},"version_base page")," for details on the version_base parameter."))),(0,i.mdx)("p",null,"See ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.3/advanced/hydra-command-line-flags"},"Hydra's command line flags")," and\n",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.3/advanced/override_grammar/basic"},"Basic Override Syntax")," for more information about the command line."))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/3d066543.38c73098.js b/assets/js/3d066543.38c73098.js deleted file mode 100644 index fa8b4a5d92..0000000000 --- a/assets/js/3d066543.38c73098.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[6048],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>p,MDXProvider:()=>d,mdx:()=>y,useMDXComponents:()=>c,withMDXComponents:()=>m});var r=n(96540);function a(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(){return i=Object.assign||function(e){for(var t=1;t=0||(a[n]=e[n]);return a}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(a[n]=e[n])}return a}var p=r.createContext({}),m=function(e){return function(t){var n=c(t.components);return r.createElement(e,i({},t,{components:n}))}},c=function(e){var t=r.useContext(p),n=t;return e&&(n="function"==typeof e?e(t):s(s({},t),e)),n},d=function(e){var t=c(e.components);return r.createElement(p.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},f=r.forwardRef((function(e,t){var n=e.components,a=e.mdxType,i=e.originalType,o=e.parentName,p=l(e,["components","mdxType","originalType","parentName"]),m=c(n),d=a,f=m["".concat(o,".").concat(d)]||m[d]||u[d]||i;return n?r.createElement(f,s(s({ref:t},p),{},{components:n})):r.createElement(f,s({ref:t},p))}));function y(e,t){var n=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var i=n.length,o=new Array(i);o[0]=f;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s.mdxType="string"==typeof e?e:a,o[1]=s;for(var p=2;p{n.d(t,{A:()=>l,C:()=>p});var r=n(58168),a=n(96540),i=n(75489),o=n(44586),s=n(74098);function l(e){return a.createElement(i.default,(0,r.A)({},e,{to:(t=e.to,l=(0,s.useActiveVersion)(),(0,o.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==l?void 0:l.name)?n:"current"]+t),target:"_blank"}));var t,n,l}function p(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return a.createElement(l,e,a.createElement("span",null,"\xa0"),a.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},2355:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>p,default:()=>u,frontMatter:()=>l,metadata:()=>m,toc:()=>c});var r=n(58168),a=n(98587),i=(n(96540),n(15680)),o=n(49595),s=["components"],l={id:"simple_cli",title:"A simple command-line application"},p=void 0,m={unversionedId:"tutorials/basic/your_first_app/simple_cli",id:"version-1.3/tutorials/basic/your_first_app/simple_cli",title:"A simple command-line application",description:"This is a simple Hydra application that prints your configuration.",source:"@site/versioned_docs/version-1.3/tutorials/basic/your_first_app/1_simple_cli.md",sourceDirName:"tutorials/basic/your_first_app",slug:"/tutorials/basic/your_first_app/simple_cli",permalink:"/docs/1.3/tutorials/basic/your_first_app/simple_cli",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/tutorials/basic/your_first_app/1_simple_cli.md",tags:[],version:"1.3",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:1,frontMatter:{id:"simple_cli",title:"A simple command-line application"},sidebar:"docs",previous:{title:"Tutorials intro",permalink:"/docs/1.3/tutorials/intro"},next:{title:"Specifying a config file",permalink:"/docs/1.3/tutorials/basic/your_first_app/config_file"}},c=[],d={toc:c};function u(e){var t=e.components,n=(0,a.A)(e,s);return(0,i.mdx)("wrapper",(0,r.A)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,i.mdx)(o.C,{to:"examples/tutorials/basic/your_first_hydra_app/1_simple_cli/my_app.py",mdxType:"ExampleGithubLink"}),(0,i.mdx)("p",null,"This is a simple Hydra application that prints your configuration.\nThe ",(0,i.mdx)("inlineCode",{parentName:"p"},"my_app")," function is a placeholder for your code.\nWe will slowly evolve this example to showcase more Hydra features."),(0,i.mdx)("p",null,"The examples in this tutorial are available ",(0,i.mdx)(o.A,{to:"examples/tutorials/basic",mdxType:"GithubLink"},"here"),"."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app.py"',title:'"my_app.py"'},'from omegaconf import DictConfig, OmegaConf\nimport hydra\n\n@hydra.main(version_base=None)\ndef my_app(cfg: DictConfig) -> None:\n print(OmegaConf.to_yaml(cfg))\n\nif __name__ == "__main__":\n my_app()\n')),(0,i.mdx)("p",null,"In this example, Hydra creates an empty ",(0,i.mdx)("inlineCode",{parentName:"p"},"cfg")," object and passes it to the function annotated with ",(0,i.mdx)("inlineCode",{parentName:"p"},"@hydra.main"),"."),(0,i.mdx)("p",null,"You can add config values via the command line. The ",(0,i.mdx)("inlineCode",{parentName:"p"},"+")," indicates that the field is new."),(0,i.mdx)("pre",null,(0,i.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py +db.driver=mysql +db.user=omry +db.password=secret\ndb:\n driver: mysql\n user: omry\n password: secret\n")),(0,i.mdx)("div",{className:"admonition admonition-info alert alert--info"},(0,i.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,i.mdx)("h5",{parentName:"div"},(0,i.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,i.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,i.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"info")),(0,i.mdx)("div",{parentName:"div",className:"admonition-content"},(0,i.mdx)("p",{parentName:"div"},"See the ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.3/upgrades/version_base"},"version_base page")," for details on the version_base parameter."))),(0,i.mdx)("p",null,"See ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.3/advanced/hydra-command-line-flags"},"Hydra's command line flags")," and\n",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.3/advanced/override_grammar/basic"},"Basic Override Syntax")," for more information about the command line."))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/3dca537e.01d4703b.js b/assets/js/3dca537e.01d4703b.js deleted file mode 100644 index 5da81befcc..0000000000 --- a/assets/js/3dca537e.01d4703b.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[1646],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>m,MDXProvider:()=>p,mdx:()=>g,useMDXComponents:()=>s,withMDXComponents:()=>c});var r=a(96540);function t(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(t[a]=e[a]);return t}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(t[a]=e[a])}return t}var m=r.createContext({}),c=function(e){return function(n){var a=s(n.components);return r.createElement(e,i({},n,{components:a}))}},s=function(e){var n=r.useContext(m),a=n;return e&&(a="function"==typeof e?e(n):l(l({},n),e)),a},p=function(e){var n=s(e.components);return r.createElement(m.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},f=r.forwardRef((function(e,n){var a=e.components,t=e.mdxType,i=e.originalType,o=e.parentName,m=d(e,["components","mdxType","originalType","parentName"]),c=s(a),p=t,f=c["".concat(o,".").concat(p)]||c[p]||u[p]||i;return a?r.createElement(f,l(l({ref:n},m),{},{components:a})):r.createElement(f,l({ref:n},m))}));function g(e,n){var a=arguments,t=n&&n.mdxType;if("string"==typeof e||t){var i=a.length,o=new Array(i);o[0]=f;var l={};for(var d in n)hasOwnProperty.call(n,d)&&(l[d]=n[d]);l.originalType=e,l.mdxType="string"==typeof e?e:t,o[1]=l;for(var m=2;m{a.r(n),a.d(n,{contentTitle:()=>d,default:()=>p,frontMatter:()=>l,metadata:()=>m,toc:()=>c});var r=a(58168),t=a(98587),i=(a(96540),a(15680)),o=["components"],l={id:"hydra-command-line-flags",title:"Hydra's command line flags"},d=void 0,m={unversionedId:"advanced/hydra-command-line-flags",id:"version-1.3/advanced/hydra-command-line-flags",title:"Hydra's command line flags",description:"Hydra is using the command line for two things:",source:"@site/versioned_docs/version-1.3/advanced/hydra-command-line-flags.md",sourceDirName:"advanced",slug:"/advanced/hydra-command-line-flags",permalink:"/docs/1.3/advanced/hydra-command-line-flags",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/advanced/hydra-command-line-flags.md",tags:[],version:"1.3",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"hydra-command-line-flags",title:"Hydra's command line flags"},sidebar:"docs",previous:{title:"Terminology",permalink:"/docs/1.3/advanced/terminology"},next:{title:"Basic Override syntax",permalink:"/docs/1.3/advanced/override_grammar/basic"}},c=[],s={toc:c};function p(e){var n=e.components,a=(0,t.A)(e,o);return(0,i.mdx)("wrapper",(0,r.A)({},s,a,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Hydra is using the command line for two things:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"Controlling Hydra"),(0,i.mdx)("li",{parentName:"ul"},"Configuring your application (See ",(0,i.mdx)("a",{parentName:"li",href:"/docs/1.3/advanced/override_grammar/basic"},"Override Grammar"),")")),(0,i.mdx)("p",null,"Arguments prefixed by - or -- control Hydra; the rest are used to configure the application."),(0,i.mdx)("p",null,"Information about Hydra:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--hydra-help"),": Shows Hydra specific flags"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--version"),": Show Hydra's version and exit")),(0,i.mdx)("p",null,"Information provided by the Hydra app:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--help,-h"),": Shows the application's help. This can be ",(0,i.mdx)("a",{parentName:"li",href:"/docs/1.3/configure_hydra/app_help"},"customized"),".")),(0,i.mdx)("p",null,"Debugging assistance:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--cfg,-c"),": Show config instead of running. Takes as parameter one of ",(0,i.mdx)("inlineCode",{parentName:"li"},"job"),", ",(0,i.mdx)("inlineCode",{parentName:"li"},"hydra")," or ",(0,i.mdx)("inlineCode",{parentName:"li"},"all"),"."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--resolve"),": Used in conjunction with the ",(0,i.mdx)("inlineCode",{parentName:"li"},"--cfg")," flag; resolve interpolations in the config before printing it."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--package,-p"),": Used in conjunction with --cfg to select a specific config package to show."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--info,-i"),": Print Hydra information. This includes installed plugins, Config Search Path, Defaults List, generated config and more.")),(0,i.mdx)("p",null,"Running Hydra applications:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--run,-r"),": Run is the default mode and is not normally needed."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--multirun,-m"),": Run multiple jobs with the configured launcher and sweeper. See ",(0,i.mdx)("a",{parentName:"li",href:"/docs/1.3/tutorials/basic/running_your_app/multi-run"},"Multi-run"),".",(0,i.mdx)("br",null),(0,i.mdx)("br",null)),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--config-path,-cp"),": Overrides the ",(0,i.mdx)("inlineCode",{parentName:"li"},"config_path")," specified in ",(0,i.mdx)("inlineCode",{parentName:"li"},"hydra.main()"),". The ",(0,i.mdx)("inlineCode",{parentName:"li"},"config_path")," is absolute or relative to the Python file declaring ",(0,i.mdx)("inlineCode",{parentName:"li"},"@hydra.main()"),"."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--config-name,-cn"),": Overrides the ",(0,i.mdx)("inlineCode",{parentName:"li"},"config_name")," specified in ",(0,i.mdx)("inlineCode",{parentName:"li"},"hydra.main()"),"."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--config-dir,-cd"),": Adds an additional config directory to the ",(0,i.mdx)("a",{parentName:"li",href:"/docs/1.3/advanced/search_path"},"config search path"),".",(0,i.mdx)("br",{parentName:"li"}),"This is useful for installed apps that want to allow their users to provide additional configs.")),(0,i.mdx)("p",null,"Misc:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--shell-completion,-sc"),": Install or Uninstall ",(0,i.mdx)("a",{parentName:"li",href:"/docs/1.3/tutorials/basic/running_your_app/tab_completion"},"shell tab completion"),".")))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/3dca537e.5f97e6af.js b/assets/js/3dca537e.5f97e6af.js new file mode 100644 index 0000000000..798fcde350 --- /dev/null +++ b/assets/js/3dca537e.5f97e6af.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[1646],{15680:(e,n,a)=>{a.r(n),a.d(n,{MDXContext:()=>m,MDXProvider:()=>p,mdx:()=>g,useMDXComponents:()=>s,withMDXComponents:()=>c});var r=a(96540);function t(e,n,a){return n in e?Object.defineProperty(e,n,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[n]=a,e}function i(){return i=Object.assign||function(e){for(var n=1;n=0||(t[a]=e[a]);return t}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(t[a]=e[a])}return t}var m=r.createContext({}),c=function(e){return function(n){var a=s(n.components);return r.createElement(e,i({},n,{components:a}))}},s=function(e){var n=r.useContext(m),a=n;return e&&(a="function"==typeof e?e(n):l(l({},n),e)),a},p=function(e){var n=s(e.components);return r.createElement(m.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return r.createElement(r.Fragment,{},n)}},f=r.forwardRef((function(e,n){var a=e.components,t=e.mdxType,i=e.originalType,o=e.parentName,m=d(e,["components","mdxType","originalType","parentName"]),c=s(a),p=t,f=c["".concat(o,".").concat(p)]||c[p]||u[p]||i;return a?r.createElement(f,l(l({ref:n},m),{},{components:a})):r.createElement(f,l({ref:n},m))}));function g(e,n){var a=arguments,t=n&&n.mdxType;if("string"==typeof e||t){var i=a.length,o=new Array(i);o[0]=f;var l={};for(var d in n)hasOwnProperty.call(n,d)&&(l[d]=n[d]);l.originalType=e,l.mdxType="string"==typeof e?e:t,o[1]=l;for(var m=2;m{a.r(n),a.d(n,{contentTitle:()=>d,default:()=>p,frontMatter:()=>l,metadata:()=>m,toc:()=>c});var r=a(58168),t=a(98587),i=(a(96540),a(15680)),o=["components"],l={id:"hydra-command-line-flags",title:"Hydra's command line flags"},d=void 0,m={unversionedId:"advanced/hydra-command-line-flags",id:"version-1.3/advanced/hydra-command-line-flags",title:"Hydra's command line flags",description:"Hydra is using the command line for two things:",source:"@site/versioned_docs/version-1.3/advanced/hydra-command-line-flags.md",sourceDirName:"advanced",slug:"/advanced/hydra-command-line-flags",permalink:"/docs/1.3/advanced/hydra-command-line-flags",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/advanced/hydra-command-line-flags.md",tags:[],version:"1.3",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"hydra-command-line-flags",title:"Hydra's command line flags"},sidebar:"docs",previous:{title:"Terminology",permalink:"/docs/1.3/advanced/terminology"},next:{title:"Basic Override syntax",permalink:"/docs/1.3/advanced/override_grammar/basic"}},c=[],s={toc:c};function p(e){var n=e.components,a=(0,t.A)(e,o);return(0,i.mdx)("wrapper",(0,r.A)({},s,a,{components:n,mdxType:"MDXLayout"}),(0,i.mdx)("p",null,"Hydra is using the command line for two things:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},"Controlling Hydra"),(0,i.mdx)("li",{parentName:"ul"},"Configuring your application (See ",(0,i.mdx)("a",{parentName:"li",href:"/docs/1.3/advanced/override_grammar/basic"},"Override Grammar"),")")),(0,i.mdx)("p",null,"Arguments prefixed by - or -- control Hydra; the rest are used to configure the application."),(0,i.mdx)("p",null,"Information about Hydra:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--hydra-help"),": Shows Hydra specific flags"),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--version"),": Show Hydra's version and exit")),(0,i.mdx)("p",null,"Information provided by the Hydra app:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--help,-h"),": Shows the application's help. This can be ",(0,i.mdx)("a",{parentName:"li",href:"/docs/1.3/configure_hydra/app_help"},"customized"),".")),(0,i.mdx)("p",null,"Debugging assistance:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--cfg,-c"),": Show config instead of running. Takes as parameter one of ",(0,i.mdx)("inlineCode",{parentName:"li"},"job"),", ",(0,i.mdx)("inlineCode",{parentName:"li"},"hydra")," or ",(0,i.mdx)("inlineCode",{parentName:"li"},"all"),"."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--resolve"),": Used in conjunction with the ",(0,i.mdx)("inlineCode",{parentName:"li"},"--cfg")," flag; resolve interpolations in the config before printing it."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--package,-p"),": Used in conjunction with --cfg to select a specific config package to show."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--info,-i"),": Print Hydra information. This includes installed plugins, Config Search Path, Defaults List, generated config and more.")),(0,i.mdx)("p",null,"Running Hydra applications:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--run,-r"),": Run is the default mode and is not normally needed."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--multirun,-m"),": Run multiple jobs with the configured launcher and sweeper. See ",(0,i.mdx)("a",{parentName:"li",href:"/docs/1.3/tutorials/basic/running_your_app/multi-run"},"Multi-run"),".",(0,i.mdx)("br",null),(0,i.mdx)("br",null)),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--config-path,-cp"),": Overrides the ",(0,i.mdx)("inlineCode",{parentName:"li"},"config_path")," specified in ",(0,i.mdx)("inlineCode",{parentName:"li"},"hydra.main()"),". The ",(0,i.mdx)("inlineCode",{parentName:"li"},"config_path")," is absolute or relative to the Python file declaring ",(0,i.mdx)("inlineCode",{parentName:"li"},"@hydra.main()"),"."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--config-name,-cn"),": Overrides the ",(0,i.mdx)("inlineCode",{parentName:"li"},"config_name")," specified in ",(0,i.mdx)("inlineCode",{parentName:"li"},"hydra.main()"),"."),(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--config-dir,-cd"),": Adds an additional config directory to the ",(0,i.mdx)("a",{parentName:"li",href:"/docs/1.3/advanced/search_path"},"config search path"),".",(0,i.mdx)("br",{parentName:"li"}),"This is useful for installed apps that want to allow their users to provide additional configs.")),(0,i.mdx)("p",null,"Misc:"),(0,i.mdx)("ul",null,(0,i.mdx)("li",{parentName:"ul"},(0,i.mdx)("strong",{parentName:"li"},"--shell-completion,-sc"),": Install or Uninstall ",(0,i.mdx)("a",{parentName:"li",href:"/docs/1.3/tutorials/basic/running_your_app/tab_completion"},"shell tab completion"),".")))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/3e16a344.9e892238.js b/assets/js/3e16a344.9e892238.js new file mode 100644 index 0000000000..ef1f5e982b --- /dev/null +++ b/assets/js/3e16a344.9e892238.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3182],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>o,MDXProvider:()=>u,mdx:()=>x,useMDXComponents:()=>p,withMDXComponents:()=>s});var a=t(96540);function r(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function l(){return l=Object.assign||function(e){for(var n=1;n=0||(r[t]=e[t]);return r}(e,n);if(Object.getOwnPropertySymbols){var l=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(r[t]=e[t])}return r}var o=a.createContext({}),s=function(e){return function(n){var t=p(n.components);return a.createElement(e,l({},n,{components:t}))}},p=function(e){var n=a.useContext(o),t=n;return e&&(t="function"==typeof e?e(n):i(i({},n),e)),t},u=function(e){var n=p(e.components);return a.createElement(o.Provider,{value:n},e.children)},g={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},c=a.forwardRef((function(e,n){var t=e.components,r=e.mdxType,l=e.originalType,d=e.parentName,o=m(e,["components","mdxType","originalType","parentName"]),s=p(t),u=r,c=s["".concat(d,".").concat(u)]||s[u]||g[u]||l;return t?a.createElement(c,i(i({ref:n},o),{},{components:t})):a.createElement(c,i({ref:n},o))}));function x(e,n){var t=arguments,r=n&&n.mdxType;if("string"==typeof e||r){var l=t.length,d=new Array(l);d[0]=c;var i={};for(var m in n)hasOwnProperty.call(n,m)&&(i[m]=n[m]);i.originalType=e,i.mdxType="string"==typeof e?e:r,d[1]=i;for(var o=2;o{t.r(n),t.d(n,{contentTitle:()=>m,default:()=>u,frontMatter:()=>i,metadata:()=>o,toc:()=>s});var a=t(58168),r=t(98587),l=(t(96540),t(15680)),d=["components"],i={id:"extended",sidebar_label:"Extended Override syntax",hide_title:!0},m=void 0,o={unversionedId:"advanced/override_grammar/extended",id:"version-1.3/advanced/override_grammar/extended",title:"extended",description:"Extended Override syntax",source:"@site/versioned_docs/version-1.3/advanced/override_grammar/extended.md",sourceDirName:"advanced/override_grammar",slug:"/advanced/override_grammar/extended",permalink:"/docs/1.3/advanced/override_grammar/extended",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/advanced/override_grammar/extended.md",tags:[],version:"1.3",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"extended",sidebar_label:"Extended Override syntax",hide_title:!0},sidebar:"docs",previous:{title:"Basic Override syntax",permalink:"/docs/1.3/advanced/override_grammar/basic"},next:{title:"The Defaults List",permalink:"/docs/1.3/advanced/defaults_list"}},s=[{value:"Extended Override syntax",id:"extended-override-syntax",children:[],level:2},{value:"Sweeps",id:"sweeps",children:[{value:"Choice sweep",id:"choice-sweep",children:[],level:3},{value:"Glob choice sweep",id:"glob-choice-sweep",children:[],level:3},{value:"Range sweep",id:"range-sweep",children:[],level:3},{value:"Interval sweep",id:"interval-sweep",children:[],level:3},{value:"Tag",id:"tag",children:[],level:3}],level:2},{value:"Reordering lists and sweeps",id:"reordering-lists-and-sweeps",children:[{value:"sort",id:"sort",children:[],level:3},{value:"shuffle",id:"shuffle",children:[],level:3}],level:2},{value:"Type casting",id:"type-casting",children:[{value:"Casting string to bool",id:"casting-string-to-bool",children:[],level:4},{value:"Casting lists",id:"casting-lists",children:[],level:4},{value:"Casting dicts",id:"casting-dicts",children:[],level:4},{value:"Casting ranges",id:"casting-ranges",children:[],level:4},{value:"Conversion matrix",id:"conversion-matrix",children:[],level:3}],level:2}],p={toc:s};function u(e){var n=e.components,t=(0,r.A)(e,d);return(0,l.mdx)("wrapper",(0,a.A)({},p,t,{components:n,mdxType:"MDXLayout"}),(0,l.mdx)("h2",{id:"extended-override-syntax"},"Extended Override syntax"),(0,l.mdx)("p",null,"Hydra Overrides supports functions.\nWhen calling a function, one can optionally name parameters. This is following the Python\nconvention of naming parameters."),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Example function"',title:'"Example','function"':!0},"def func(a:int, b:str) -> bool:\n ...\n\n\n"))),(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Calling function"',title:'"Calling','function"':!0},"func(10,foo) # Positional only\nfunc(a=10,b=foo) # Named only\nfunc(10,b=foo) # Mixed\nfunc(a=10,foo) # Error\n")))),(0,l.mdx)("p",null,"Note the lack of quotes in the examples above. Despite some similarities, this is ",(0,l.mdx)("strong",{parentName:"p"},"not Python"),"."),(0,l.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,l.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,l.mdx)("h5",{parentName:"div"},(0,l.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,l.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,l.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,l.mdx)("div",{parentName:"div",className:"admonition-content"},(0,l.mdx)("p",{parentName:"div"},"Hydra supports very specific functions. If you would like to have\nanother function added, please file an issue and explain the use case."))),(0,l.mdx)("h2",{id:"sweeps"},"Sweeps"),(0,l.mdx)("p",null,"Sweep overrides are used by Sweepers to determine what to do. For example,\none can instruct the Basic Sweeper to sweep over all combinations of the\nranges ",(0,l.mdx)("inlineCode",{parentName:"p"},"num1=range(0,3)")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"num2=range(0,3)")," - resulting in ",(0,l.mdx)("inlineCode",{parentName:"p"},"9")," jobs, each getting a\ndifferent pair of numbers from ",(0,l.mdx)("inlineCode",{parentName:"p"},"0"),", ",(0,l.mdx)("inlineCode",{parentName:"p"},"1")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"2"),"."),(0,l.mdx)("h3",{id:"choice-sweep"},"Choice sweep"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def choice(\n *args: Union[str, int, float, bool, Dict[Any, Any], List[Any], ChoiceSweep]\n) -> ChoiceSweep:\n """\n A choice sweep over the specified values\n """\n')),(0,l.mdx)("p",null,"Choice sweeps are the most common sweeps.\nA choice sweep is described in one of two equivalent forms."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"db=mysql,postgresql # a comma separated list of two or more elements. \ndb=choice(mysql,postgresql) # choice\n")),(0,l.mdx)("h3",{id:"glob-choice-sweep"},"Glob choice sweep"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def glob(\n include: Union[List[str], str], exclude: Optional[Union[List[str], str]] = None\n) -> Glob:\n """\n A glob selects from all options in the config group.\n inputs are in glob format. e.g: *, foo*, *foo.\n :param include: a string or a list of strings to use as include globs\n :param exclude: a string or a list of strings to use as exclude globs\n :return: A Glob object\n """\n')),(0,l.mdx)("p",null,"Assuming the config group ",(0,l.mdx)("strong",{parentName:"p"},"schema")," with the options ",(0,l.mdx)("strong",{parentName:"p"},"school"),", ",(0,l.mdx)("strong",{parentName:"p"},"support")," and ",(0,l.mdx)("strong",{parentName:"p"},"warehouse"),":"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"schema=glob(*) # school,support,warehouse\nschema=glob(*,exclude=support) # school,warehouse\nschema=glob([s*,w*],exclude=school) # support,warehouse\n")),(0,l.mdx)("h3",{id:"range-sweep"},"Range sweep"),(0,l.mdx)("p",null,"Unlike Python, Hydra's range can be used with both integer and floating-point numbers.\nIn both cases, the range represents a discrete list of values."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def range(\n start: Union[int, float], stop: Optional[Union[int, float]] = None, step: Union[int, float] = 1\n) -> RangeSweep:\n """\n Range is defines a sweeep over a range of integer or floating-point values.\n For a positive step, the contents of a range r are determined by the formula\n r[i] = start + step*i where i >= 0 and r[i] < stop.\n For a negative step, the contents of the range are still determined by the formula\n r[i] = start + step*i, but the constraints are i >= 0 and r[i] > stop.\n """\n')),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"num=range(5) # 0,1,2,3,4\nnum=range(0,5) # 0,1,2,3,4\nnum=range(0,5,2) # 0,2,4\nnum=range(0,10,3.3) # 0.0,3.3,6.6,9.9\nnum=range(-5,step=-1) # 0,-1,-2,-3,-4\n")),(0,l.mdx)("h3",{id:"interval-sweep"},"Interval sweep"),(0,l.mdx)("p",null,"An interval sweep represents all the floating point value between two values.\nThis is used by optimizing sweepers like Ax and Nevergrad. The basic sweeper does not support interval."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def interval(start: Union[int, float], end: Union[int, float]) -> IntervalSweep:\n """\n A continuous interval between two floating point values.\n value=interval(x,y) is interpreted as x <= value < y\n """\n')),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"interval(1.0,5.0) # 1.0 <= x < 5.0\ninterval(1,5) # 1.0 <= x < 5.0, auto-cast to floats\n")),(0,l.mdx)("h3",{id:"tag"},"Tag"),(0,l.mdx)("p",null,"With tags you can add arbitrary metadata to a sweep. The metadata can be used by advanced sweepers."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def tag(*args: Union[str, Union[Sweep]], sweep: Optional[Sweep] = None) -> Sweep:\n """\n Tags the sweep with a list of string tags.\n """\n')),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"tag(log,interval(0,1)) # 1.0 <= x < 1.0, tags=[log]\ntag(foo,bar,interval(0,1)) # 1.0 <= x < 1.0, tags=[foo,bar]\n")),(0,l.mdx)("h2",{id:"reordering-lists-and-sweeps"},"Reordering lists and sweeps"),(0,l.mdx)("h3",{id:"sort"},"sort"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def sort(\n *args: Union[ElementType, ChoiceSweep, RangeSweep],\n sweep: Optional[Union[ChoiceSweep, RangeSweep]] = None,\n list: Optional[List[Any]] = None,\n reverse: bool = False,\n) -> Any:\n """\n Sort an input list or sweep.\n reverse=True reverses the order\n """\n')),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"# sweep\nsort(1,3,2) # ChoiceSweep(1,2,3)\nsort(1,3,2,reverse=true) # ChoiceSweep(3,2,1)\nsort(choice(1,2,3)) # ChoiceSweep(1,2,3)\nsort(sweep=choice(1,2,3)) # ChoiceSweep(1,2,3)\nsort(choice(1,2,3),reverse=true) # ChoiceSweep(3,2,1)\nsort(range(10,1)) # range in ascending order\nsort(range(1,10),reverse=true) # range in descending order\n\n# lists\nsort([1,3,2]) # [1,2,3]\nsort(list=[1,3,2]) # [1,2,3]\nsort(list=[1,3,2], reverse=true) # [3,2,1]\n\n# single value returned as is\nsort(1) # 1\n")),(0,l.mdx)("h3",{id:"shuffle"},"shuffle"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def shuffle(\n *args: Union[ElementType, ChoiceSweep, RangeSweep],\n sweep: Optional[Union[ChoiceSweep, RangeSweep]] = None,\n list: Optional[List[Any]] = None,\n) -> Union[List[Any], ChoiceSweep, RangeSweep]:\n """\n Shuffle input list or sweep (does not support interval)\n """\n')),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"shuffle(a,b,c) # shuffled a,b,c\nshuffle(choice(a,b,c)), shuffle(sweep=choice(a,b,c)) # shuffled choice(a,b,c)\nshuffle(range(1,10)) # shuffled range(1,10)\nshuffle([a,b,c]), shuffle(list=[a,b,c]) # shuffled list [a,b,c] \n")),(0,l.mdx)("h2",{id:"type-casting"},"Type casting"),(0,l.mdx)("p",null,"You can cast values and sweeps to ",(0,l.mdx)("inlineCode",{parentName:"p"},"int"),", ",(0,l.mdx)("inlineCode",{parentName:"p"},"float"),", ",(0,l.mdx)("inlineCode",{parentName:"p"},"bool")," or ",(0,l.mdx)("inlineCode",{parentName:"p"},"str"),"."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Example"',title:'"Example"'},"int(3.14) # 3 (int)\nint(value=3.14) # 3 (int)\nfloat(10) # 10.0 (float)\nstr(10) # \"10\" (str)\nbool(1) # true (bool)\nfloat(range(1,10)) # range(1.0,10.0)\nstr([1,2,3]) # ['1','2','3']\nstr({a:10}) # {a:'10'}\n")),(0,l.mdx)("p",null,"Below are pseudo code snippets that illustrates the differences between Python's casting and Hydra's casting."),(0,l.mdx)("h4",{id:"casting-string-to-bool"},"Casting string to bool"),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Python"',title:'"Python"'},"def bool(value: Any) -> bool:\n if isinstance(value, str):\n return len(value) > 0\n else:\n return bool(value)\n\n\n\n\n"))),(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Hydra"',title:'"Hydra"'},'def bool(s: str) -> bool:\n if isinstance(value, str):\n if value.lower() == "false":\n return False\n elif value.lower() == "true":\n return True\n else:\n raise ValueError()\n return bool(value)\n')))),(0,l.mdx)("h4",{id:"casting-lists"},"Casting lists"),(0,l.mdx)("p",null,"Casting lists results in a list where each element is recursively cast.\nFailure to cast an element in the list fails the cast of the list."),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Python"',title:'"Python"'},"def cast_int(value: Any):\n if isinstance(value, list):\n raise TypeError()\n else:\n return int(v)\n\n\n"))),(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Hydra"',title:'"Hydra"'},"def cast_int(value: Any):\n if isinstance(v, list):\n return list(map(cast_int, v))\n else:\n return int(v)\n\n\n")))),(0,l.mdx)("h4",{id:"casting-dicts"},"Casting dicts"),(0,l.mdx)("p",null,"Casting dicts results in a dict where values are recursively cast, but keys are unchanged.\nFailure to cast a value in the dict fails the cast of the entire dict."),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Python"',title:'"Python"'},"def cast_int(value: Any):\n if isinstance(value, dict):\n raise TypeError()\n else:\n return int(v)\n\n\n"))),(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Hydra"',title:'"Hydra"'},"def cast_int(value: Any):\n if isinstance(value, dict):\n return apply_to_values(\n value, cast_int\n )\n else:\n return int(v)\n")))),(0,l.mdx)("h4",{id:"casting-ranges"},"Casting ranges"),(0,l.mdx)("p",null,"Ranges can be cast to float or int, resulting in start, stop and step being cast and thus the range elements being cast."),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Python"',title:'"Python"'},"def cast_int(value: Any):\n if isinstance(value, RangeSweep):\n raise TypeError()\n else:\n return int(v)\n\n\n\n\n"))),(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Hydra"',title:'"Hydra"'},"def cast_int(value: Any):\n if isinstance(value, RangeSweep):\n return RangeSweep(\n start=cast_int(value.start),\n stop=cast_int(value.stop),\n step=cast_int(value.step),\n )\n else:\n return int(v)\n")))),(0,l.mdx)("h3",{id:"conversion-matrix"},"Conversion matrix"),(0,l.mdx)("p",null,"Below is the conversion matrix from various inputs to all supported types.\nInput are grouped by type."),(0,l.mdx)("table",null,(0,l.mdx)("thead",{parentName:"table"},(0,l.mdx)("tr",{parentName:"thead"},(0,l.mdx)("th",{parentName:"tr",align:null}),(0,l.mdx)("th",{parentName:"tr",align:null},"int()"),(0,l.mdx)("th",{parentName:"tr",align:null},"float()"),(0,l.mdx)("th",{parentName:"tr",align:null},"str()"),(0,l.mdx)("th",{parentName:"tr",align:null},"bool()"))),(0,l.mdx)("tbody",{parentName:"table"},(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"10"),(0,l.mdx)("td",{parentName:"tr",align:null},"10"),(0,l.mdx)("td",{parentName:"tr",align:null},"10.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c10\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"0"),(0,l.mdx)("td",{parentName:"tr",align:null},"0"),(0,l.mdx)("td",{parentName:"tr",align:null},"0.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c0\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"false")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"10.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"10"),(0,l.mdx)("td",{parentName:"tr",align:null},"10.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c10.0\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"0.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"0"),(0,l.mdx)("td",{parentName:"tr",align:null},"0.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c0.0\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"false")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"inf"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"inf"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u2018inf\u2019"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"nan"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"nan"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u2018nan\u2019"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"1e6"),(0,l.mdx)("td",{parentName:"tr",align:null},"1,000,000"),(0,l.mdx)("td",{parentName:"tr",align:null},"1e6"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u20181000000.0\u2019"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"foo"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"foo"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c\u201d (empty string)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c10\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"10"),(0,l.mdx)("td",{parentName:"tr",align:null},"10.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c10\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c10.0\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"10.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c10.0\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201ctrue\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201ctrue\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201cfalse\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201cfalse\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"false")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c","[1,2,3]","\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c","[1,2,3]","\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c{a:10}\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c{a:10}\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"1"),(0,l.mdx)("td",{parentName:"tr",align:null},"1.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201ctrue\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"0"),(0,l.mdx)("td",{parentName:"tr",align:null},"0.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201cfalse\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"false")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"[]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[]")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"[0,1,2]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[0,1,2]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[0.0,1.0,2.0]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[\u201c0\u201d,\u201d1\u201d,\u201d2\u201d]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[false,true,true]")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"[1,","[2]","]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[1,","[2]","]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[1.0,","[2.0]","]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[\u201c1\u201d,","[\u201c2\u201d]","]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[true,","[true]","]")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"[a,1]"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"[\u201ca\u201d,\u201d1\u201d]"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"{}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{}")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"{a:10}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:10}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:10.0}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:\u201d10\u201d}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a: true}")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"{a:","[0,1,2]","}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:","[0,1,2]","}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:","[0.0,1.0,2.-]","}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:","[\u201c0\u201d,\u201d1\u201d,\u201d2\u201d]","}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:","[false,true,true]","}")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"{a:10,b:xyz}"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:\u201d10\u201d,b:\u201dxyz\u201d}"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"choice(0,1)"),(0,l.mdx)("td",{parentName:"tr",align:null},"choice(0,1)"),(0,l.mdx)("td",{parentName:"tr",align:null},"choice(0.0,1.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"choice(\u201c0\u201d,\u201c1\u201d)"),(0,l.mdx)("td",{parentName:"tr",align:null},"choice(false,true)")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"choice(a,b)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"choice(\u201ca\u201d,\u201db\u201d)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"choice(1,a)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"choice(\u201c1\u201d,\u201da\u201d)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"interval(1.0, 2.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"interval(1, 2)"),(0,l.mdx)("td",{parentName:"tr",align:null},"interval(1.0, 2.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"interval(1, 2)"),(0,l.mdx)("td",{parentName:"tr",align:null},"interval(1, 2)"),(0,l.mdx)("td",{parentName:"tr",align:null},"interval(1.0, 2.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"range(1,10)"),(0,l.mdx)("td",{parentName:"tr",align:null},"range(1,10)"),(0,l.mdx)("td",{parentName:"tr",align:null},"range(1.0,10.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"range(1.0, 10.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"range(1,10)"),(0,l.mdx)("td",{parentName:"tr",align:null},"range(1.0,10.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")))))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/3e16a344.ffcd0851.js b/assets/js/3e16a344.ffcd0851.js deleted file mode 100644 index 346b30d25a..0000000000 --- a/assets/js/3e16a344.ffcd0851.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3182],{15680:(e,n,t)=>{t.r(n),t.d(n,{MDXContext:()=>o,MDXProvider:()=>u,mdx:()=>x,useMDXComponents:()=>p,withMDXComponents:()=>s});var a=t(96540);function r(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function l(){return l=Object.assign||function(e){for(var n=1;n=0||(r[t]=e[t]);return r}(e,n);if(Object.getOwnPropertySymbols){var l=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(r[t]=e[t])}return r}var o=a.createContext({}),s=function(e){return function(n){var t=p(n.components);return a.createElement(e,l({},n,{components:t}))}},p=function(e){var n=a.useContext(o),t=n;return e&&(t="function"==typeof e?e(n):i(i({},n),e)),t},u=function(e){var n=p(e.components);return a.createElement(o.Provider,{value:n},e.children)},g={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},c=a.forwardRef((function(e,n){var t=e.components,r=e.mdxType,l=e.originalType,d=e.parentName,o=m(e,["components","mdxType","originalType","parentName"]),s=p(t),u=r,c=s["".concat(d,".").concat(u)]||s[u]||g[u]||l;return t?a.createElement(c,i(i({ref:n},o),{},{components:t})):a.createElement(c,i({ref:n},o))}));function x(e,n){var t=arguments,r=n&&n.mdxType;if("string"==typeof e||r){var l=t.length,d=new Array(l);d[0]=c;var i={};for(var m in n)hasOwnProperty.call(n,m)&&(i[m]=n[m]);i.originalType=e,i.mdxType="string"==typeof e?e:r,d[1]=i;for(var o=2;o{t.r(n),t.d(n,{contentTitle:()=>m,default:()=>u,frontMatter:()=>i,metadata:()=>o,toc:()=>s});var a=t(58168),r=t(98587),l=(t(96540),t(15680)),d=["components"],i={id:"extended",sidebar_label:"Extended Override syntax",hide_title:!0},m=void 0,o={unversionedId:"advanced/override_grammar/extended",id:"version-1.3/advanced/override_grammar/extended",title:"extended",description:"Extended Override syntax",source:"@site/versioned_docs/version-1.3/advanced/override_grammar/extended.md",sourceDirName:"advanced/override_grammar",slug:"/advanced/override_grammar/extended",permalink:"/docs/1.3/advanced/override_grammar/extended",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/advanced/override_grammar/extended.md",tags:[],version:"1.3",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"extended",sidebar_label:"Extended Override syntax",hide_title:!0},sidebar:"docs",previous:{title:"Basic Override syntax",permalink:"/docs/1.3/advanced/override_grammar/basic"},next:{title:"The Defaults List",permalink:"/docs/1.3/advanced/defaults_list"}},s=[{value:"Extended Override syntax",id:"extended-override-syntax",children:[],level:2},{value:"Sweeps",id:"sweeps",children:[{value:"Choice sweep",id:"choice-sweep",children:[],level:3},{value:"Glob choice sweep",id:"glob-choice-sweep",children:[],level:3},{value:"Range sweep",id:"range-sweep",children:[],level:3},{value:"Interval sweep",id:"interval-sweep",children:[],level:3},{value:"Tag",id:"tag",children:[],level:3}],level:2},{value:"Reordering lists and sweeps",id:"reordering-lists-and-sweeps",children:[{value:"sort",id:"sort",children:[],level:3},{value:"shuffle",id:"shuffle",children:[],level:3}],level:2},{value:"Type casting",id:"type-casting",children:[{value:"Casting string to bool",id:"casting-string-to-bool",children:[],level:4},{value:"Casting lists",id:"casting-lists",children:[],level:4},{value:"Casting dicts",id:"casting-dicts",children:[],level:4},{value:"Casting ranges",id:"casting-ranges",children:[],level:4},{value:"Conversion matrix",id:"conversion-matrix",children:[],level:3}],level:2}],p={toc:s};function u(e){var n=e.components,t=(0,r.A)(e,d);return(0,l.mdx)("wrapper",(0,a.A)({},p,t,{components:n,mdxType:"MDXLayout"}),(0,l.mdx)("h2",{id:"extended-override-syntax"},"Extended Override syntax"),(0,l.mdx)("p",null,"Hydra Overrides supports functions.\nWhen calling a function, one can optionally name parameters. This is following the Python\nconvention of naming parameters."),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Example function"',title:'"Example','function"':!0},"def func(a:int, b:str) -> bool:\n ...\n\n\n"))),(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Calling function"',title:'"Calling','function"':!0},"func(10,foo) # Positional only\nfunc(a=10,b=foo) # Named only\nfunc(10,b=foo) # Mixed\nfunc(a=10,foo) # Error\n")))),(0,l.mdx)("p",null,"Note the lack of quotes in the examples above. Despite some similarities, this is ",(0,l.mdx)("strong",{parentName:"p"},"not Python"),"."),(0,l.mdx)("div",{className:"admonition admonition-important alert alert--info"},(0,l.mdx)("div",{parentName:"div",className:"admonition-heading"},(0,l.mdx)("h5",{parentName:"div"},(0,l.mdx)("span",{parentName:"h5",className:"admonition-icon"},(0,l.mdx)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,l.mdx)("path",{parentName:"svg",fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"}))),"important")),(0,l.mdx)("div",{parentName:"div",className:"admonition-content"},(0,l.mdx)("p",{parentName:"div"},"Hydra supports very specific functions. If you would like to have\nanother function added, please file an issue and explain the use case."))),(0,l.mdx)("h2",{id:"sweeps"},"Sweeps"),(0,l.mdx)("p",null,"Sweep overrides are used by Sweepers to determine what to do. For example,\none can instruct the Basic Sweeper to sweep over all combinations of the\nranges ",(0,l.mdx)("inlineCode",{parentName:"p"},"num1=range(0,3)")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"num2=range(0,3)")," - resulting in ",(0,l.mdx)("inlineCode",{parentName:"p"},"9")," jobs, each getting a\ndifferent pair of numbers from ",(0,l.mdx)("inlineCode",{parentName:"p"},"0"),", ",(0,l.mdx)("inlineCode",{parentName:"p"},"1")," and ",(0,l.mdx)("inlineCode",{parentName:"p"},"2"),"."),(0,l.mdx)("h3",{id:"choice-sweep"},"Choice sweep"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def choice(\n *args: Union[str, int, float, bool, Dict[Any, Any], List[Any], ChoiceSweep]\n) -> ChoiceSweep:\n """\n A choice sweep over the specified values\n """\n')),(0,l.mdx)("p",null,"Choice sweeps are the most common sweeps.\nA choice sweep is described in one of two equivalent forms."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"db=mysql,postgresql # a comma separated list of two or more elements. \ndb=choice(mysql,postgresql) # choice\n")),(0,l.mdx)("h3",{id:"glob-choice-sweep"},"Glob choice sweep"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def glob(\n include: Union[List[str], str], exclude: Optional[Union[List[str], str]] = None\n) -> Glob:\n """\n A glob selects from all options in the config group.\n inputs are in glob format. e.g: *, foo*, *foo.\n :param include: a string or a list of strings to use as include globs\n :param exclude: a string or a list of strings to use as exclude globs\n :return: A Glob object\n """\n')),(0,l.mdx)("p",null,"Assuming the config group ",(0,l.mdx)("strong",{parentName:"p"},"schema")," with the options ",(0,l.mdx)("strong",{parentName:"p"},"school"),", ",(0,l.mdx)("strong",{parentName:"p"},"support")," and ",(0,l.mdx)("strong",{parentName:"p"},"warehouse"),":"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"schema=glob(*) # school,support,warehouse\nschema=glob(*,exclude=support) # school,warehouse\nschema=glob([s*,w*],exclude=school) # support,warehouse\n")),(0,l.mdx)("h3",{id:"range-sweep"},"Range sweep"),(0,l.mdx)("p",null,"Unlike Python, Hydra's range can be used with both integer and floating-point numbers.\nIn both cases, the range represents a discrete list of values."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def range(\n start: Union[int, float], stop: Optional[Union[int, float]] = None, step: Union[int, float] = 1\n) -> RangeSweep:\n """\n Range is defines a sweeep over a range of integer or floating-point values.\n For a positive step, the contents of a range r are determined by the formula\n r[i] = start + step*i where i >= 0 and r[i] < stop.\n For a negative step, the contents of the range are still determined by the formula\n r[i] = start + step*i, but the constraints are i >= 0 and r[i] > stop.\n """\n')),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"num=range(5) # 0,1,2,3,4\nnum=range(0,5) # 0,1,2,3,4\nnum=range(0,5,2) # 0,2,4\nnum=range(0,10,3.3) # 0.0,3.3,6.6,9.9\nnum=range(-5,step=-1) # 0,-1,-2,-3,-4\n")),(0,l.mdx)("h3",{id:"interval-sweep"},"Interval sweep"),(0,l.mdx)("p",null,"An interval sweep represents all the floating point value between two values.\nThis is used by optimizing sweepers like Ax and Nevergrad. The basic sweeper does not support interval."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def interval(start: Union[int, float], end: Union[int, float]) -> IntervalSweep:\n """\n A continuous interval between two floating point values.\n value=interval(x,y) is interpreted as x <= value < y\n """\n')),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"interval(1.0,5.0) # 1.0 <= x < 5.0\ninterval(1,5) # 1.0 <= x < 5.0, auto-cast to floats\n")),(0,l.mdx)("h3",{id:"tag"},"Tag"),(0,l.mdx)("p",null,"With tags you can add arbitrary metadata to a sweep. The metadata can be used by advanced sweepers."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def tag(*args: Union[str, Union[Sweep]], sweep: Optional[Sweep] = None) -> Sweep:\n """\n Tags the sweep with a list of string tags.\n """\n')),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"tag(log,interval(0,1)) # 1.0 <= x < 1.0, tags=[log]\ntag(foo,bar,interval(0,1)) # 1.0 <= x < 1.0, tags=[foo,bar]\n")),(0,l.mdx)("h2",{id:"reordering-lists-and-sweeps"},"Reordering lists and sweeps"),(0,l.mdx)("h3",{id:"sort"},"sort"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def sort(\n *args: Union[ElementType, ChoiceSweep, RangeSweep],\n sweep: Optional[Union[ChoiceSweep, RangeSweep]] = None,\n list: Optional[List[Any]] = None,\n reverse: bool = False,\n) -> Any:\n """\n Sort an input list or sweep.\n reverse=True reverses the order\n """\n')),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"# sweep\nsort(1,3,2) # ChoiceSweep(1,2,3)\nsort(1,3,2,reverse=true) # ChoiceSweep(3,2,1)\nsort(choice(1,2,3)) # ChoiceSweep(1,2,3)\nsort(sweep=choice(1,2,3)) # ChoiceSweep(1,2,3)\nsort(choice(1,2,3),reverse=true) # ChoiceSweep(3,2,1)\nsort(range(10,1)) # range in ascending order\nsort(range(1,10),reverse=true) # range in descending order\n\n# lists\nsort([1,3,2]) # [1,2,3]\nsort(list=[1,3,2]) # [1,2,3]\nsort(list=[1,3,2], reverse=true) # [3,2,1]\n\n# single value returned as is\nsort(1) # 1\n")),(0,l.mdx)("h3",{id:"shuffle"},"shuffle"),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Signature"',title:'"Signature"'},'def shuffle(\n *args: Union[ElementType, ChoiceSweep, RangeSweep],\n sweep: Optional[Union[ChoiceSweep, RangeSweep]] = None,\n list: Optional[List[Any]] = None,\n) -> Union[List[Any], ChoiceSweep, RangeSweep]:\n """\n Shuffle input list or sweep (does not support interval)\n """\n')),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Examples"',title:'"Examples"'},"shuffle(a,b,c) # shuffled a,b,c\nshuffle(choice(a,b,c)), shuffle(sweep=choice(a,b,c)) # shuffled choice(a,b,c)\nshuffle(range(1,10)) # shuffled range(1,10)\nshuffle([a,b,c]), shuffle(list=[a,b,c]) # shuffled list [a,b,c] \n")),(0,l.mdx)("h2",{id:"type-casting"},"Type casting"),(0,l.mdx)("p",null,"You can cast values and sweeps to ",(0,l.mdx)("inlineCode",{parentName:"p"},"int"),", ",(0,l.mdx)("inlineCode",{parentName:"p"},"float"),", ",(0,l.mdx)("inlineCode",{parentName:"p"},"bool")," or ",(0,l.mdx)("inlineCode",{parentName:"p"},"str"),"."),(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Example"',title:'"Example"'},"int(3.14) # 3 (int)\nint(value=3.14) # 3 (int)\nfloat(10) # 10.0 (float)\nstr(10) # \"10\" (str)\nbool(1) # true (bool)\nfloat(range(1,10)) # range(1.0,10.0)\nstr([1,2,3]) # ['1','2','3']\nstr({a:10}) # {a:'10'}\n")),(0,l.mdx)("p",null,"Below are pseudo code snippets that illustrates the differences between Python's casting and Hydra's casting."),(0,l.mdx)("h4",{id:"casting-string-to-bool"},"Casting string to bool"),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Python"',title:'"Python"'},"def bool(value: Any) -> bool:\n if isinstance(value, str):\n return len(value) > 0\n else:\n return bool(value)\n\n\n\n\n"))),(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Hydra"',title:'"Hydra"'},'def bool(s: str) -> bool:\n if isinstance(value, str):\n if value.lower() == "false":\n return False\n elif value.lower() == "true":\n return True\n else:\n raise ValueError()\n return bool(value)\n')))),(0,l.mdx)("h4",{id:"casting-lists"},"Casting lists"),(0,l.mdx)("p",null,"Casting lists results in a list where each element is recursively cast.\nFailure to cast an element in the list fails the cast of the list."),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Python"',title:'"Python"'},"def cast_int(value: Any):\n if isinstance(value, list):\n raise TypeError()\n else:\n return int(v)\n\n\n"))),(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Hydra"',title:'"Hydra"'},"def cast_int(value: Any):\n if isinstance(v, list):\n return list(map(cast_int, v))\n else:\n return int(v)\n\n\n")))),(0,l.mdx)("h4",{id:"casting-dicts"},"Casting dicts"),(0,l.mdx)("p",null,"Casting dicts results in a dict where values are recursively cast, but keys are unchanged.\nFailure to cast a value in the dict fails the cast of the entire dict."),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Python"',title:'"Python"'},"def cast_int(value: Any):\n if isinstance(value, dict):\n raise TypeError()\n else:\n return int(v)\n\n\n"))),(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Hydra"',title:'"Hydra"'},"def cast_int(value: Any):\n if isinstance(value, dict):\n return apply_to_values(\n value, cast_int\n )\n else:\n return int(v)\n")))),(0,l.mdx)("h4",{id:"casting-ranges"},"Casting ranges"),(0,l.mdx)("p",null,"Ranges can be cast to float or int, resulting in start, stop and step being cast and thus the range elements being cast."),(0,l.mdx)("div",{className:"row"},(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Python"',title:'"Python"'},"def cast_int(value: Any):\n if isinstance(value, RangeSweep):\n raise TypeError()\n else:\n return int(v)\n\n\n\n\n"))),(0,l.mdx)("div",{className:"col col--6"},(0,l.mdx)("pre",null,(0,l.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Hydra"',title:'"Hydra"'},"def cast_int(value: Any):\n if isinstance(value, RangeSweep):\n return RangeSweep(\n start=cast_int(value.start),\n stop=cast_int(value.stop),\n step=cast_int(value.step),\n )\n else:\n return int(v)\n")))),(0,l.mdx)("h3",{id:"conversion-matrix"},"Conversion matrix"),(0,l.mdx)("p",null,"Below is the conversion matrix from various inputs to all supported types.\nInput are grouped by type."),(0,l.mdx)("table",null,(0,l.mdx)("thead",{parentName:"table"},(0,l.mdx)("tr",{parentName:"thead"},(0,l.mdx)("th",{parentName:"tr",align:null}),(0,l.mdx)("th",{parentName:"tr",align:null},"int()"),(0,l.mdx)("th",{parentName:"tr",align:null},"float()"),(0,l.mdx)("th",{parentName:"tr",align:null},"str()"),(0,l.mdx)("th",{parentName:"tr",align:null},"bool()"))),(0,l.mdx)("tbody",{parentName:"table"},(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"10"),(0,l.mdx)("td",{parentName:"tr",align:null},"10"),(0,l.mdx)("td",{parentName:"tr",align:null},"10.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c10\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"0"),(0,l.mdx)("td",{parentName:"tr",align:null},"0"),(0,l.mdx)("td",{parentName:"tr",align:null},"0.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c0\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"false")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"10.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"10"),(0,l.mdx)("td",{parentName:"tr",align:null},"10.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c10.0\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"0.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"0"),(0,l.mdx)("td",{parentName:"tr",align:null},"0.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c0.0\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"false")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"inf"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"inf"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u2018inf\u2019"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"nan"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"nan"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u2018nan\u2019"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"1e6"),(0,l.mdx)("td",{parentName:"tr",align:null},"1,000,000"),(0,l.mdx)("td",{parentName:"tr",align:null},"1e6"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u20181000000.0\u2019"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"foo"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"foo"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c\u201d (empty string)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c10\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"10"),(0,l.mdx)("td",{parentName:"tr",align:null},"10.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c10\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c10.0\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"10.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c10.0\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201ctrue\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201ctrue\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201cfalse\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201cfalse\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"false")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c","[1,2,3]","\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c","[1,2,3]","\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c{a:10}\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201c{a:10}\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"true"),(0,l.mdx)("td",{parentName:"tr",align:null},"1"),(0,l.mdx)("td",{parentName:"tr",align:null},"1.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201ctrue\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"true")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"false"),(0,l.mdx)("td",{parentName:"tr",align:null},"0"),(0,l.mdx)("td",{parentName:"tr",align:null},"0.0"),(0,l.mdx)("td",{parentName:"tr",align:null},"\u201cfalse\u201d"),(0,l.mdx)("td",{parentName:"tr",align:null},"false")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"[]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[]")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"[0,1,2]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[0,1,2]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[0.0,1.0,2.0]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[\u201c0\u201d,\u201d1\u201d,\u201d2\u201d]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[false,true,true]")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"[1,","[2]","]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[1,","[2]","]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[1.0,","[2.0]","]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[\u201c1\u201d,","[\u201c2\u201d]","]"),(0,l.mdx)("td",{parentName:"tr",align:null},"[true,","[true]","]")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"[a,1]"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"[\u201ca\u201d,\u201d1\u201d]"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"{}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{}")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"{a:10}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:10}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:10.0}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:\u201d10\u201d}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a: true}")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"{a:","[0,1,2]","}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:","[0,1,2]","}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:","[0.0,1.0,2.-]","}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:","[\u201c0\u201d,\u201d1\u201d,\u201d2\u201d]","}"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:","[false,true,true]","}")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"{a:10,b:xyz}"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"{a:\u201d10\u201d,b:\u201dxyz\u201d}"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"choice(0,1)"),(0,l.mdx)("td",{parentName:"tr",align:null},"choice(0,1)"),(0,l.mdx)("td",{parentName:"tr",align:null},"choice(0.0,1.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"choice(\u201c0\u201d,\u201c1\u201d)"),(0,l.mdx)("td",{parentName:"tr",align:null},"choice(false,true)")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"choice(a,b)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"choice(\u201ca\u201d,\u201db\u201d)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"choice(1,a)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"choice(\u201c1\u201d,\u201da\u201d)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"interval(1.0, 2.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"interval(1, 2)"),(0,l.mdx)("td",{parentName:"tr",align:null},"interval(1.0, 2.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"interval(1, 2)"),(0,l.mdx)("td",{parentName:"tr",align:null},"interval(1, 2)"),(0,l.mdx)("td",{parentName:"tr",align:null},"interval(1.0, 2.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"range(1,10)"),(0,l.mdx)("td",{parentName:"tr",align:null},"range(1,10)"),(0,l.mdx)("td",{parentName:"tr",align:null},"range(1.0,10.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")),(0,l.mdx)("tr",{parentName:"tbody"},(0,l.mdx)("td",{parentName:"tr",align:null},"range(1.0, 10.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"range(1,10)"),(0,l.mdx)("td",{parentName:"tr",align:null},"range(1.0,10.0)"),(0,l.mdx)("td",{parentName:"tr",align:null},"error"),(0,l.mdx)("td",{parentName:"tr",align:null},"error")))))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/3e5c2e49.5a80897c.js b/assets/js/3e5c2e49.5a80897c.js deleted file mode 100644 index 6e1e897d4d..0000000000 --- a/assets/js/3e5c2e49.5a80897c.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[5561],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>d,MDXProvider:()=>p,mdx:()=>g,useMDXComponents:()=>c,withMDXComponents:()=>m});var a=n(96540);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function r(){return r=Object.assign||function(e){for(var t=1;t=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var d=a.createContext({}),m=function(e){return function(t){var n=c(t.components);return a.createElement(e,r({},t,{components:n}))}},c=function(e){var t=a.useContext(d),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},p=function(e){var t=c(e.components);return a.createElement(d.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},f=a.forwardRef((function(e,t){var n=e.components,i=e.mdxType,r=e.originalType,o=e.parentName,d=s(e,["components","mdxType","originalType","parentName"]),m=c(n),p=i,f=m["".concat(o,".").concat(p)]||m[p]||u[p]||r;return n?a.createElement(f,l(l({ref:t},d),{},{components:n})):a.createElement(f,l({ref:t},d))}));function g(e,t){var n=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var r=n.length,o=new Array(r);o[0]=f;var l={};for(var s in t)hasOwnProperty.call(t,s)&&(l[s]=t[s]);l.originalType=e,l.mdxType="string"==typeof e?e:i,o[1]=l;for(var d=2;d{n.r(t),n.d(t,{contentTitle:()=>s,default:()=>p,frontMatter:()=>l,metadata:()=>d,toc:()=>m});var a=n(58168),i=n(98587),r=(n(96540),n(15680)),o=["components"],l={id:"default_composition_order",title:"Changes to default composition order"},s=void 0,d={unversionedId:"upgrades/1.0_to_1.1/default_composition_order",id:"version-1.3/upgrades/1.0_to_1.1/default_composition_order",title:"Changes to default composition order",description:"Default composition order is changing in Hydra 1.1.",source:"@site/versioned_docs/version-1.3/upgrades/1.0_to_1.1/changes_to_default_composition_order.md",sourceDirName:"upgrades/1.0_to_1.1",slug:"/upgrades/1.0_to_1.1/default_composition_order",permalink:"/docs/1.3/upgrades/1.0_to_1.1/default_composition_order",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/upgrades/1.0_to_1.1/changes_to_default_composition_order.md",tags:[],version:"1.3",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"default_composition_order",title:"Changes to default composition order"},sidebar:"docs",previous:{title:"Changes to @hydra.main() and hydra.initialize()",permalink:"/docs/1.3/upgrades/1.0_to_1.1/changes_to_hydra_main_config_path"},next:{title:"Defaults List Overrides",permalink:"/docs/1.3/upgrades/1.0_to_1.1/defaults_list_override"}},m=[{value:"Migration",id:"migration",children:[{value:"Primary config is a YAML file",id:"primary-config-is-a-yaml-file",children:[],level:3},{value:"Primary config is a Structured Config",id:"primary-config-is-a-structured-config",children:[],level:3},{value:"Primary config is a config file with a Structured Config schema",id:"primary-config-is-a-config-file-with-a-structured-config-schema",children:[],level:3},{value:"Compatibility with both Hydra 1.0 and 1.1",id:"compatibility-with-both-hydra-10-and-11",children:[],level:3}],level:2}],c={toc:m};function p(e){var t=e.components,n=(0,i.A)(e,o);return(0,r.mdx)("wrapper",(0,a.A)({},c,n,{components:t,mdxType:"MDXLayout"}),(0,r.mdx)("p",null,"Default composition order is changing in Hydra 1.1."),(0,r.mdx)("p",null,"For this example, let's assume the following two configs:"),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - foo: bar\n\nfoo:\n x: 10\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="foo/bar.yaml"',title:'"foo/bar.yaml"'},"# @package _group_\nx: 20\n\n\n\n")))),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col"},(0,r.mdx)("p",null,"In ",(0,r.mdx)("strong",{parentName:"p"},"Hydra 1.0"),", configs from the Defaults List are overriding ",(0,r.mdx)("em",{parentName:"p"},"config.yaml"),", resulting in the following output:")),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{2}","{2}":!0},"foo:\n x: 20\n")))),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col"},(0,r.mdx)("p",null,"As of ",(0,r.mdx)("strong",{parentName:"p"},"Hydra 1.1"),", ",(0,r.mdx)("em",{parentName:"p"},"config.yaml")," is overriding configs from the Defaults List, resulting in the following output:")),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{2}","{2}":!0},"foo:\n x: 10\n")))),(0,r.mdx)("h2",{id:"migration"},"Migration"),(0,r.mdx)("p",null,"If your application uses ",(0,r.mdx)("inlineCode",{parentName:"p"},"hydra.main"),", the best way to verify that updating Hydra versions does not change your job configurations is to compare the output of ",(0,r.mdx)("inlineCode",{parentName:"p"},"python my_app.py --cfg job")," on both the new and old Hydra versions. If your application uses the Compose API, please make sure you have comprehensive unit tests on the composed configuration."),(0,r.mdx)("h3",{id:"primary-config-is-a-yaml-file"},"Primary config is a YAML file"),(0,r.mdx)("p",null,"To ensure this change is not missed by people migrating from Hydra 1.0, Hydra 1.1 issues a warning if the Defaults List in the primary config is missing ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_"),", and there are config values in addition to the Defaults List.",(0,r.mdx)("br",{parentName:"p"}),"\n","To address the warning, add ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," to the Defaults List of the primary config."),(0,r.mdx)("ul",null,(0,r.mdx)("li",{parentName:"ul"},"If the new behavior works for your application, append ",(0,r.mdx)("inlineCode",{parentName:"li"},"_self_")," to the end of the Defaults List."),(0,r.mdx)("li",{parentName:"ul"},"If your application requires the previous behavior, insert ",(0,r.mdx)("inlineCode",{parentName:"li"},"_self_")," as the first item in your Defaults List.")),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {2}',title:'"config.yaml"',"{2}":!0},"defaults:\n - _self_\n - foo: bar\n\nfoo:\n x: 10\n"))),(0,r.mdx)("div",{className:"col col--6"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Output config"',title:'"Output','config"':!0},"foo:\n x: 20\n\n\n\n\n")))),(0,r.mdx)("p",null,"The Defaults List is described ",(0,r.mdx)("a",{parentName:"p",href:"/docs/1.3/advanced/defaults_list"},"here"),"."),(0,r.mdx)("h3",{id:"primary-config-is-a-structured-config"},"Primary config is a Structured Config"),(0,r.mdx)("p",null,"Structured Configs used as primary config may see changes as well.\nYou should add ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," to the defaults list to indicate the composition order. In such cases you will typically want ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," to be the first item in the defaults list. "),(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python",metastring:"{3,14}","{3,14}":!0},'defaults = [\n "_self_",\n {"db": "mysql"}\n]\n\n@dataclass\nclass Config:\n # this is unfortunately verbose due to @dataclass limitations\n defaults: List[Any] = field(default_factory=lambda: defaults)\n\n # Hydra will populate this field based on the defaults list\n db: Any = MISSING\n')),(0,r.mdx)("h3",{id:"primary-config-is-a-config-file-with-a-structured-config-schema"},"Primary config is a config file with a Structured Config schema"),(0,r.mdx)("p",null,"If you use Structured Config as a schema for your primary config, be sure to add ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," after the schema in the Defaults List, otherwise the schema will override the config instead of the other way around."),(0,r.mdx)("div",{className:"row"},(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app.py"',title:'"my_app.py"'},'@dataclass\nclass Config:\n host: str = "localhost"\n port: int = 8080\n\ncs.store(name="base_config", \n node=Config)\n'))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'{3,5} title="config.yaml"',"{3,5}":!0,title:'"config.yaml"'},"defaults:\n - base_config # schema\n - _self_ # after schema\n\nport: 3306\n\n\n"))),(0,r.mdx)("div",{className:"col col--4"},(0,r.mdx)("pre",null,(0,r.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'{2} title="Output config"',"{2}":!0,title:'"Output','config"':!0},"host: localhost # schema\nport: 3306 # config.yaml\n\n\n\n\n\n")))),(0,r.mdx)("h3",{id:"compatibility-with-both-hydra-10-and-11"},"Compatibility with both Hydra 1.0 and 1.1"),(0,r.mdx)("p",null,"If your config must be compatible with both Hydra 1.0 and 1.1, Insert ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," as the first item in the Defaults List.\nHydra 1.0.7 (or newer releases in Hydra 1.0) ignores ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," in the Defaults List and Hydra 1.1 will compose the same config as Hydra 1.0 if ",(0,r.mdx)("inlineCode",{parentName:"p"},"_self_")," is the first item."))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/3e5c2e49.fee2dfb3.js b/assets/js/3e5c2e49.fee2dfb3.js new file mode 100644 index 0000000000..2150781113 --- /dev/null +++ b/assets/js/3e5c2e49.fee2dfb3.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[5561],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>d,MDXProvider:()=>p,mdx:()=>g,useMDXComponents:()=>c,withMDXComponents:()=>m});var a=n(96540);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var d=a.createContext({}),m=function(e){return function(t){var n=c(t.components);return a.createElement(e,o({},t,{components:n}))}},c=function(e){var t=a.useContext(d),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},p=function(e){var t=c(e.components);return a.createElement(d.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},f=a.forwardRef((function(e,t){var n=e.components,i=e.mdxType,o=e.originalType,r=e.parentName,d=s(e,["components","mdxType","originalType","parentName"]),m=c(n),p=i,f=m["".concat(r,".").concat(p)]||m[p]||u[p]||o;return n?a.createElement(f,l(l({ref:t},d),{},{components:n})):a.createElement(f,l({ref:t},d))}));function g(e,t){var n=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var o=n.length,r=new Array(o);r[0]=f;var l={};for(var s in t)hasOwnProperty.call(t,s)&&(l[s]=t[s]);l.originalType=e,l.mdxType="string"==typeof e?e:i,r[1]=l;for(var d=2;d{n.r(t),n.d(t,{contentTitle:()=>s,default:()=>p,frontMatter:()=>l,metadata:()=>d,toc:()=>m});var a=n(58168),i=n(98587),o=(n(96540),n(15680)),r=["components"],l={id:"default_composition_order",title:"Changes to default composition order"},s=void 0,d={unversionedId:"upgrades/1.0_to_1.1/default_composition_order",id:"version-1.3/upgrades/1.0_to_1.1/default_composition_order",title:"Changes to default composition order",description:"Default composition order is changing in Hydra 1.1.",source:"@site/versioned_docs/version-1.3/upgrades/1.0_to_1.1/changes_to_default_composition_order.md",sourceDirName:"upgrades/1.0_to_1.1",slug:"/upgrades/1.0_to_1.1/default_composition_order",permalink:"/docs/1.3/upgrades/1.0_to_1.1/default_composition_order",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/upgrades/1.0_to_1.1/changes_to_default_composition_order.md",tags:[],version:"1.3",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"default_composition_order",title:"Changes to default composition order"},sidebar:"docs",previous:{title:"Changes to @hydra.main() and hydra.initialize()",permalink:"/docs/1.3/upgrades/1.0_to_1.1/changes_to_hydra_main_config_path"},next:{title:"Defaults List Overrides",permalink:"/docs/1.3/upgrades/1.0_to_1.1/defaults_list_override"}},m=[{value:"Migration",id:"migration",children:[{value:"Primary config is a YAML file",id:"primary-config-is-a-yaml-file",children:[],level:3},{value:"Primary config is a Structured Config",id:"primary-config-is-a-structured-config",children:[],level:3},{value:"Primary config is a config file with a Structured Config schema",id:"primary-config-is-a-config-file-with-a-structured-config-schema",children:[],level:3},{value:"Compatibility with both Hydra 1.0 and 1.1",id:"compatibility-with-both-hydra-10-and-11",children:[],level:3}],level:2}],c={toc:m};function p(e){var t=e.components,n=(0,i.A)(e,r);return(0,o.mdx)("wrapper",(0,a.A)({},c,n,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"Default composition order is changing in Hydra 1.1."),(0,o.mdx)("p",null,"For this example, let's assume the following two configs:"),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"defaults:\n - foo: bar\n\nfoo:\n x: 10\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="foo/bar.yaml"',title:'"foo/bar.yaml"'},"# @package _group_\nx: 20\n\n\n\n")))),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col"},(0,o.mdx)("p",null,"In ",(0,o.mdx)("strong",{parentName:"p"},"Hydra 1.0"),", configs from the Defaults List are overriding ",(0,o.mdx)("em",{parentName:"p"},"config.yaml"),", resulting in the following output:")),(0,o.mdx)("div",{className:"col col--4"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{2}","{2}":!0},"foo:\n x: 20\n")))),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col"},(0,o.mdx)("p",null,"As of ",(0,o.mdx)("strong",{parentName:"p"},"Hydra 1.1"),", ",(0,o.mdx)("em",{parentName:"p"},"config.yaml")," is overriding configs from the Defaults List, resulting in the following output:")),(0,o.mdx)("div",{className:"col col--4"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:"{2}","{2}":!0},"foo:\n x: 10\n")))),(0,o.mdx)("h2",{id:"migration"},"Migration"),(0,o.mdx)("p",null,"If your application uses ",(0,o.mdx)("inlineCode",{parentName:"p"},"hydra.main"),", the best way to verify that updating Hydra versions does not change your job configurations is to compare the output of ",(0,o.mdx)("inlineCode",{parentName:"p"},"python my_app.py --cfg job")," on both the new and old Hydra versions. If your application uses the Compose API, please make sure you have comprehensive unit tests on the composed configuration."),(0,o.mdx)("h3",{id:"primary-config-is-a-yaml-file"},"Primary config is a YAML file"),(0,o.mdx)("p",null,"To ensure this change is not missed by people migrating from Hydra 1.0, Hydra 1.1 issues a warning if the Defaults List in the primary config is missing ",(0,o.mdx)("inlineCode",{parentName:"p"},"_self_"),", and there are config values in addition to the Defaults List.",(0,o.mdx)("br",{parentName:"p"}),"\n","To address the warning, add ",(0,o.mdx)("inlineCode",{parentName:"p"},"_self_")," to the Defaults List of the primary config."),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"If the new behavior works for your application, append ",(0,o.mdx)("inlineCode",{parentName:"li"},"_self_")," to the end of the Defaults List."),(0,o.mdx)("li",{parentName:"ul"},"If your application requires the previous behavior, insert ",(0,o.mdx)("inlineCode",{parentName:"li"},"_self_")," as the first item in your Defaults List.")),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml" {2}',title:'"config.yaml"',"{2}":!0},"defaults:\n - _self_\n - foo: bar\n\nfoo:\n x: 10\n"))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Output config"',title:'"Output','config"':!0},"foo:\n x: 20\n\n\n\n\n")))),(0,o.mdx)("p",null,"The Defaults List is described ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.3/advanced/defaults_list"},"here"),"."),(0,o.mdx)("h3",{id:"primary-config-is-a-structured-config"},"Primary config is a Structured Config"),(0,o.mdx)("p",null,"Structured Configs used as primary config may see changes as well.\nYou should add ",(0,o.mdx)("inlineCode",{parentName:"p"},"_self_")," to the defaults list to indicate the composition order. In such cases you will typically want ",(0,o.mdx)("inlineCode",{parentName:"p"},"_self_")," to be the first item in the defaults list. "),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:"{3,14}","{3,14}":!0},'defaults = [\n "_self_",\n {"db": "mysql"}\n]\n\n@dataclass\nclass Config:\n # this is unfortunately verbose due to @dataclass limitations\n defaults: List[Any] = field(default_factory=lambda: defaults)\n\n # Hydra will populate this field based on the defaults list\n db: Any = MISSING\n')),(0,o.mdx)("h3",{id:"primary-config-is-a-config-file-with-a-structured-config-schema"},"Primary config is a config file with a Structured Config schema"),(0,o.mdx)("p",null,"If you use Structured Config as a schema for your primary config, be sure to add ",(0,o.mdx)("inlineCode",{parentName:"p"},"_self_")," after the schema in the Defaults List, otherwise the schema will override the config instead of the other way around."),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--4"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="my_app.py"',title:'"my_app.py"'},'@dataclass\nclass Config:\n host: str = "localhost"\n port: int = 8080\n\ncs.store(name="base_config", \n node=Config)\n'))),(0,o.mdx)("div",{className:"col col--4"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'{3,5} title="config.yaml"',"{3,5}":!0,title:'"config.yaml"'},"defaults:\n - base_config # schema\n - _self_ # after schema\n\nport: 3306\n\n\n"))),(0,o.mdx)("div",{className:"col col--4"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml",metastring:'{2} title="Output config"',"{2}":!0,title:'"Output','config"':!0},"host: localhost # schema\nport: 3306 # config.yaml\n\n\n\n\n\n")))),(0,o.mdx)("h3",{id:"compatibility-with-both-hydra-10-and-11"},"Compatibility with both Hydra 1.0 and 1.1"),(0,o.mdx)("p",null,"If your config must be compatible with both Hydra 1.0 and 1.1, Insert ",(0,o.mdx)("inlineCode",{parentName:"p"},"_self_")," as the first item in the Defaults List.\nHydra 1.0.7 (or newer releases in Hydra 1.0) ignores ",(0,o.mdx)("inlineCode",{parentName:"p"},"_self_")," in the Defaults List and Hydra 1.1 will compose the same config as Hydra 1.0 if ",(0,o.mdx)("inlineCode",{parentName:"p"},"_self_")," is the first item."))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/3e7cc949.048183fb.js b/assets/js/3e7cc949.048183fb.js deleted file mode 100644 index ea2f621b6b..0000000000 --- a/assets/js/3e7cc949.048183fb.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[8400],{15680:(e,t,r)=>{r.r(t),r.d(t,{MDXContext:()=>u,MDXProvider:()=>m,mdx:()=>g,useMDXComponents:()=>d,withMDXComponents:()=>c});var n=r(96540);function i(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(i[r]=e[r]);return i}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(i[r]=e[r])}return i}var u=n.createContext({}),c=function(e){return function(t){var r=d(t.components);return n.createElement(e,o({},t,{components:r}))}},d=function(e){var t=n.useContext(u),r=t;return e&&(r="function"==typeof e?e(t):s(s({},t),e)),r},m=function(e){var t=d(e.components);return n.createElement(u.Provider,{value:t},e.children)},p={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},f=n.forwardRef((function(e,t){var r=e.components,i=e.mdxType,o=e.originalType,a=e.parentName,u=l(e,["components","mdxType","originalType","parentName"]),c=d(r),m=i,f=c["".concat(a,".").concat(m)]||c[m]||p[m]||o;return r?n.createElement(f,s(s({ref:t},u),{},{components:r})):n.createElement(f,s({ref:t},u))}));function g(e,t){var r=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var o=r.length,a=new Array(o);a[0]=f;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s.mdxType="string"==typeof e?e:i,a[1]=s;for(var u=2;u{r.d(t,{A:()=>l,C:()=>u});var n=r(58168),i=r(96540),o=r(75489),a=r(44586),s=r(74098);function l(e){return i.createElement(o.default,(0,n.A)({},e,{to:(t=e.to,l=(0,s.useActiveVersion)(),(0,a.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(r=null==l?void 0:l.name)?r:"current"]+t),target:"_blank"}));var t,r,l}function u(e){var t,r=null!=(t=e.text)?t:"Example (Click Here)";return i.createElement(l,e,i.createElement("span",null,"\xa0"),i.createElement("img",{src:"https://img.shields.io/badge/-"+r+"-informational",alt:"Example (Click Here)"}))}},14907:(e,t,r)=>{r.r(t),r.d(t,{contentTitle:()=>u,default:()=>p,frontMatter:()=>l,metadata:()=>c,toc:()=>d});var n=r(58168),i=r(98587),o=(r(96540),r(15680)),a=r(49595),s=["components"],l={id:"intro",title:"Introduction to Structured Configs",sidebar_label:"Introduction to Structured Configs"},u=void 0,c={unversionedId:"tutorials/structured_config/intro",id:"version-1.0/tutorials/structured_config/intro",title:"Introduction to Structured Configs",description:"This is an advanced tutorial that assumes that you are comfortable with the concepts introduced in the Basic Tutorial.",source:"@site/versioned_docs/version-1.0/tutorials/structured_config/0_intro.md",sourceDirName:"tutorials/structured_config",slug:"/tutorials/structured_config/intro",permalink:"/docs/1.0/tutorials/structured_config/intro",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.0/tutorials/structured_config/0_intro.md",tags:[],version:"1.0",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:0,frontMatter:{id:"intro",title:"Introduction to Structured Configs",sidebar_label:"Introduction to Structured Configs"},sidebar:"version-1.0/docs",previous:{title:"Tab completion",permalink:"/docs/1.0/tutorials/basic/running_your_app/tab_completion"},next:{title:"Minimal example",permalink:"/docs/1.0/tutorials/structured_config/minimal_example"}},d=[{value:"Structured Configs supports:",id:"structured-configs-supports",children:[],level:4},{value:"Structured Configs Limitations:",id:"structured-configs-limitations",children:[],level:4},{value:"There are two primary patterns for using Structured configs",id:"there-are-two-primary-patterns-for-using-structured-configs",children:[],level:4}],m={toc:d};function p(e){var t=e.components,r=(0,i.A)(e,s);return(0,o.mdx)("wrapper",(0,n.A)({},m,r,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"This is an advanced tutorial that assumes that you are comfortable with the concepts introduced in the ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.0/tutorials/basic/your_first_app/simple_cli"},"Basic Tutorial"),".\nThe examples in this tutorial are available ",(0,o.mdx)(a.A,{to:"examples/tutorials/structured_configs",mdxType:"GithubLink"},"here"),"."),(0,o.mdx)("p",null,"Structured Configs use Python ",(0,o.mdx)("a",{parentName:"p",href:"https://docs.python.org/3.7/library/dataclasses.html"},"dataclasses")," to\ndescribe your configuration structure and types. They enable:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("strong",{parentName:"li"},"Runtime type checking")," as you compose or mutate your config "),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("strong",{parentName:"li"},"Static type checking")," when using static type checkers (mypy, PyCharm, etc.)")),(0,o.mdx)("h4",{id:"structured-configs-supports"},"Structured Configs supports:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"Primitive types (",(0,o.mdx)("inlineCode",{parentName:"li"},"int"),", ",(0,o.mdx)("inlineCode",{parentName:"li"},"bool"),", ",(0,o.mdx)("inlineCode",{parentName:"li"},"float"),", ",(0,o.mdx)("inlineCode",{parentName:"li"},"str"),", ",(0,o.mdx)("inlineCode",{parentName:"li"},"Enums"),") "),(0,o.mdx)("li",{parentName:"ul"},"Nesting of Structured Configs"),(0,o.mdx)("li",{parentName:"ul"},"Containers (List and Dict) containing primitives or Structured Configs"),(0,o.mdx)("li",{parentName:"ul"},"Optional fields")),(0,o.mdx)("h4",{id:"structured-configs-limitations"},"Structured Configs Limitations:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"Union")," types are not supported (except ",(0,o.mdx)("inlineCode",{parentName:"li"},"Optional"),")"),(0,o.mdx)("li",{parentName:"ul"},"User methods are not supported")),(0,o.mdx)("h4",{id:"there-are-two-primary-patterns-for-using-structured-configs"},"There are two primary patterns for using Structured configs"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"As a ",(0,o.mdx)("a",{parentName:"li",href:"/docs/1.0/tutorials/structured_config/minimal_example"},"config"),", in place of configuration files (often a starting place)"),(0,o.mdx)("li",{parentName:"ul"},"As a ",(0,o.mdx)("a",{parentName:"li",href:"/docs/1.0/tutorials/structured_config/schema"},"config schema")," validating configuration files (better for complex use cases)")),(0,o.mdx)("p",null,"With both patterns, you still get everything Hydra has to offer (config composition, Command line overrides etc).\nThis tutorial covers both. ","*",(0,o.mdx)("strong",{parentName:"p"},"Read it in order"),"*","."),(0,o.mdx)("p",null,"Hydra supports OmegaConf's Structured Configs via the ",(0,o.mdx)("inlineCode",{parentName:"p"},"ConfigStore")," API.\nThis tutorial does not assume any knowledge of them.\nIt is recommended that you visit the ",(0,o.mdx)("a",{class:"external",href:"https://omegaconf.readthedocs.io/en/latest/structured_config.html",target:"_blank"},"OmegaConf Structured Configs page")," to learn more later."),(0,o.mdx)("div",{class:"alert alert--info",role:"alert"},"1. The ConfigStore API is new and subject to change.",(0,o.mdx)("br",null),"2. OmegaConf's Structured Configs are new.",(0,o.mdx)("br",null),"Please report any issues.",(0,o.mdx)("br",null)),(0,o.mdx)("br",null))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/3e7cc949.72c70a34.js b/assets/js/3e7cc949.72c70a34.js new file mode 100644 index 0000000000..7e336b52dc --- /dev/null +++ b/assets/js/3e7cc949.72c70a34.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[8400],{15680:(e,t,r)=>{r.r(t),r.d(t,{MDXContext:()=>u,MDXProvider:()=>m,mdx:()=>g,useMDXComponents:()=>d,withMDXComponents:()=>c});var n=r(96540);function i(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(i[r]=e[r]);return i}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(i[r]=e[r])}return i}var u=n.createContext({}),c=function(e){return function(t){var r=d(t.components);return n.createElement(e,o({},t,{components:r}))}},d=function(e){var t=n.useContext(u),r=t;return e&&(r="function"==typeof e?e(t):s(s({},t),e)),r},m=function(e){var t=d(e.components);return n.createElement(u.Provider,{value:t},e.children)},p={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},f=n.forwardRef((function(e,t){var r=e.components,i=e.mdxType,o=e.originalType,a=e.parentName,u=l(e,["components","mdxType","originalType","parentName"]),c=d(r),m=i,f=c["".concat(a,".").concat(m)]||c[m]||p[m]||o;return r?n.createElement(f,s(s({ref:t},u),{},{components:r})):n.createElement(f,s({ref:t},u))}));function g(e,t){var r=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var o=r.length,a=new Array(o);a[0]=f;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s.mdxType="string"==typeof e?e:i,a[1]=s;for(var u=2;u{r.d(t,{A:()=>l,C:()=>u});var n=r(58168),i=r(96540),o=r(75489),a=r(44586),s=r(74098);function l(e){return i.createElement(o.default,(0,n.A)({},e,{to:(t=e.to,l=(0,s.useActiveVersion)(),(0,a.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(r=null==l?void 0:l.name)?r:"current"]+t),target:"_blank"}));var t,r,l}function u(e){var t,r=null!=(t=e.text)?t:"Example (Click Here)";return i.createElement(l,e,i.createElement("span",null,"\xa0"),i.createElement("img",{src:"https://img.shields.io/badge/-"+r+"-informational",alt:"Example (Click Here)"}))}},14907:(e,t,r)=>{r.r(t),r.d(t,{contentTitle:()=>u,default:()=>p,frontMatter:()=>l,metadata:()=>c,toc:()=>d});var n=r(58168),i=r(98587),o=(r(96540),r(15680)),a=r(49595),s=["components"],l={id:"intro",title:"Introduction to Structured Configs",sidebar_label:"Introduction to Structured Configs"},u=void 0,c={unversionedId:"tutorials/structured_config/intro",id:"version-1.0/tutorials/structured_config/intro",title:"Introduction to Structured Configs",description:"This is an advanced tutorial that assumes that you are comfortable with the concepts introduced in the Basic Tutorial.",source:"@site/versioned_docs/version-1.0/tutorials/structured_config/0_intro.md",sourceDirName:"tutorials/structured_config",slug:"/tutorials/structured_config/intro",permalink:"/docs/1.0/tutorials/structured_config/intro",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.0/tutorials/structured_config/0_intro.md",tags:[],version:"1.0",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",sidebarPosition:0,frontMatter:{id:"intro",title:"Introduction to Structured Configs",sidebar_label:"Introduction to Structured Configs"},sidebar:"version-1.0/docs",previous:{title:"Tab completion",permalink:"/docs/1.0/tutorials/basic/running_your_app/tab_completion"},next:{title:"Minimal example",permalink:"/docs/1.0/tutorials/structured_config/minimal_example"}},d=[{value:"Structured Configs supports:",id:"structured-configs-supports",children:[],level:4},{value:"Structured Configs Limitations:",id:"structured-configs-limitations",children:[],level:4},{value:"There are two primary patterns for using Structured configs",id:"there-are-two-primary-patterns-for-using-structured-configs",children:[],level:4}],m={toc:d};function p(e){var t=e.components,r=(0,i.A)(e,s);return(0,o.mdx)("wrapper",(0,n.A)({},m,r,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)("p",null,"This is an advanced tutorial that assumes that you are comfortable with the concepts introduced in the ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.0/tutorials/basic/your_first_app/simple_cli"},"Basic Tutorial"),".\nThe examples in this tutorial are available ",(0,o.mdx)(a.A,{to:"examples/tutorials/structured_configs",mdxType:"GithubLink"},"here"),"."),(0,o.mdx)("p",null,"Structured Configs use Python ",(0,o.mdx)("a",{parentName:"p",href:"https://docs.python.org/3.7/library/dataclasses.html"},"dataclasses")," to\ndescribe your configuration structure and types. They enable:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("strong",{parentName:"li"},"Runtime type checking")," as you compose or mutate your config "),(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("strong",{parentName:"li"},"Static type checking")," when using static type checkers (mypy, PyCharm, etc.)")),(0,o.mdx)("h4",{id:"structured-configs-supports"},"Structured Configs supports:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"Primitive types (",(0,o.mdx)("inlineCode",{parentName:"li"},"int"),", ",(0,o.mdx)("inlineCode",{parentName:"li"},"bool"),", ",(0,o.mdx)("inlineCode",{parentName:"li"},"float"),", ",(0,o.mdx)("inlineCode",{parentName:"li"},"str"),", ",(0,o.mdx)("inlineCode",{parentName:"li"},"Enums"),") "),(0,o.mdx)("li",{parentName:"ul"},"Nesting of Structured Configs"),(0,o.mdx)("li",{parentName:"ul"},"Containers (List and Dict) containing primitives or Structured Configs"),(0,o.mdx)("li",{parentName:"ul"},"Optional fields")),(0,o.mdx)("h4",{id:"structured-configs-limitations"},"Structured Configs Limitations:"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},(0,o.mdx)("inlineCode",{parentName:"li"},"Union")," types are not supported (except ",(0,o.mdx)("inlineCode",{parentName:"li"},"Optional"),")"),(0,o.mdx)("li",{parentName:"ul"},"User methods are not supported")),(0,o.mdx)("h4",{id:"there-are-two-primary-patterns-for-using-structured-configs"},"There are two primary patterns for using Structured configs"),(0,o.mdx)("ul",null,(0,o.mdx)("li",{parentName:"ul"},"As a ",(0,o.mdx)("a",{parentName:"li",href:"/docs/1.0/tutorials/structured_config/minimal_example"},"config"),", in place of configuration files (often a starting place)"),(0,o.mdx)("li",{parentName:"ul"},"As a ",(0,o.mdx)("a",{parentName:"li",href:"/docs/1.0/tutorials/structured_config/schema"},"config schema")," validating configuration files (better for complex use cases)")),(0,o.mdx)("p",null,"With both patterns, you still get everything Hydra has to offer (config composition, Command line overrides etc).\nThis tutorial covers both. ","*",(0,o.mdx)("strong",{parentName:"p"},"Read it in order"),"*","."),(0,o.mdx)("p",null,"Hydra supports OmegaConf's Structured Configs via the ",(0,o.mdx)("inlineCode",{parentName:"p"},"ConfigStore")," API.\nThis tutorial does not assume any knowledge of them.\nIt is recommended that you visit the ",(0,o.mdx)("a",{class:"external",href:"https://omegaconf.readthedocs.io/en/latest/structured_config.html",target:"_blank"},"OmegaConf Structured Configs page")," to learn more later."),(0,o.mdx)("div",{class:"alert alert--info",role:"alert"},"1. The ConfigStore API is new and subject to change.",(0,o.mdx)("br",null),"2. OmegaConf's Structured Configs are new.",(0,o.mdx)("br",null),"Please report any issues.",(0,o.mdx)("br",null)),(0,o.mdx)("br",null))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/3f08a60a.93c9a510.js b/assets/js/3f08a60a.93c9a510.js deleted file mode 100644 index 90ddeb4c03..0000000000 --- a/assets/js/3f08a60a.93c9a510.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[4400],{15680:(e,t,r)=>{r.r(t),r.d(t,{MDXContext:()=>l,MDXProvider:()=>d,mdx:()=>y,useMDXComponents:()=>p,withMDXComponents:()=>u});var n=r(96540);function o(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function i(){return i=Object.assign||function(e){for(var t=1;t=0||(o[r]=e[r]);return o}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(o[r]=e[r])}return o}var l=n.createContext({}),u=function(e){return function(t){var r=p(t.components);return n.createElement(e,i({},t,{components:r}))}},p=function(e){var t=n.useContext(l),r=t;return e&&(r="function"==typeof e?e(t):c(c({},t),e)),r},d=function(e){var t=p(e.components);return n.createElement(l.Provider,{value:t},e.children)},f={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},m=n.forwardRef((function(e,t){var r=e.components,o=e.mdxType,i=e.originalType,a=e.parentName,l=s(e,["components","mdxType","originalType","parentName"]),u=p(r),d=o,m=u["".concat(a,".").concat(d)]||u[d]||f[d]||i;return r?n.createElement(m,c(c({ref:t},l),{},{components:r})):n.createElement(m,c({ref:t},l))}));function y(e,t){var r=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var i=r.length,a=new Array(i);a[0]=m;var c={};for(var s in t)hasOwnProperty.call(t,s)&&(c[s]=t[s]);c.originalType=e,c.mdxType="string"==typeof e?e:o,a[1]=c;for(var l=2;l{r.r(t),r.d(t,{contentTitle:()=>s,default:()=>d,frontMatter:()=>c,metadata:()=>l,toc:()=>u});var n=r(58168),o=r(98587),i=(r(96540),r(15680)),a=["components"],c={id:"intro",title:"Tutorials intro"},s=void 0,l={unversionedId:"tutorials/intro",id:"version-1.0/tutorials/intro",title:"Tutorials intro",description:"Basic Tutorial",source:"@site/versioned_docs/version-1.0/tutorials/intro.md",sourceDirName:"tutorials",slug:"/tutorials/intro",permalink:"/docs/1.0/tutorials/intro",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.0/tutorials/intro.md",tags:[],version:"1.0",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",frontMatter:{id:"intro",title:"Tutorials intro"},sidebar:"version-1.0/docs",previous:{title:"Terminology",permalink:"/docs/1.0/terminology"},next:{title:"A simple command-line application",permalink:"/docs/1.0/tutorials/basic/your_first_app/simple_cli"}},u=[{value:"Basic Tutorial",id:"basic-tutorial",children:[],level:3},{value:"Structured configs",id:"structured-configs",children:[],level:3}],p={toc:u};function d(e){var t=e.components,r=(0,o.A)(e,a);return(0,i.mdx)("wrapper",(0,n.A)({},p,r,{components:t,mdxType:"MDXLayout"}),(0,i.mdx)("h3",{id:"basic-tutorial"},"Basic Tutorial"),(0,i.mdx)("p",null,"The ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.0/tutorials/basic/your_first_app/simple_cli"},"Basic Tutorial")," covers basic Hydra concepts."),(0,i.mdx)("h3",{id:"structured-configs"},"Structured configs"),(0,i.mdx)("p",null,"The ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.0/tutorials/structured_config/intro"},"Structured Configs Tutorial")," shows how to create strongly typed configurations."))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/3f08a60a.946442ed.js b/assets/js/3f08a60a.946442ed.js new file mode 100644 index 0000000000..43e561d66e --- /dev/null +++ b/assets/js/3f08a60a.946442ed.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[4400],{15680:(e,t,r)=>{r.r(t),r.d(t,{MDXContext:()=>l,MDXProvider:()=>d,mdx:()=>y,useMDXComponents:()=>p,withMDXComponents:()=>u});var n=r(96540);function o(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function i(){return i=Object.assign||function(e){for(var t=1;t=0||(o[r]=e[r]);return o}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(o[r]=e[r])}return o}var l=n.createContext({}),u=function(e){return function(t){var r=p(t.components);return n.createElement(e,i({},t,{components:r}))}},p=function(e){var t=n.useContext(l),r=t;return e&&(r="function"==typeof e?e(t):c(c({},t),e)),r},d=function(e){var t=p(e.components);return n.createElement(l.Provider,{value:t},e.children)},f={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},m=n.forwardRef((function(e,t){var r=e.components,o=e.mdxType,i=e.originalType,a=e.parentName,l=s(e,["components","mdxType","originalType","parentName"]),u=p(r),d=o,m=u["".concat(a,".").concat(d)]||u[d]||f[d]||i;return r?n.createElement(m,c(c({ref:t},l),{},{components:r})):n.createElement(m,c({ref:t},l))}));function y(e,t){var r=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var i=r.length,a=new Array(i);a[0]=m;var c={};for(var s in t)hasOwnProperty.call(t,s)&&(c[s]=t[s]);c.originalType=e,c.mdxType="string"==typeof e?e:o,a[1]=c;for(var l=2;l{r.r(t),r.d(t,{contentTitle:()=>s,default:()=>d,frontMatter:()=>c,metadata:()=>l,toc:()=>u});var n=r(58168),o=r(98587),i=(r(96540),r(15680)),a=["components"],c={id:"intro",title:"Tutorials intro"},s=void 0,l={unversionedId:"tutorials/intro",id:"version-1.0/tutorials/intro",title:"Tutorials intro",description:"Basic Tutorial",source:"@site/versioned_docs/version-1.0/tutorials/intro.md",sourceDirName:"tutorials",slug:"/tutorials/intro",permalink:"/docs/1.0/tutorials/intro",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.0/tutorials/intro.md",tags:[],version:"1.0",lastUpdatedBy:"dependabot[bot]",lastUpdatedAt:1727796611,formattedLastUpdatedAt:"10/1/2024",frontMatter:{id:"intro",title:"Tutorials intro"},sidebar:"version-1.0/docs",previous:{title:"Terminology",permalink:"/docs/1.0/terminology"},next:{title:"A simple command-line application",permalink:"/docs/1.0/tutorials/basic/your_first_app/simple_cli"}},u=[{value:"Basic Tutorial",id:"basic-tutorial",children:[],level:3},{value:"Structured configs",id:"structured-configs",children:[],level:3}],p={toc:u};function d(e){var t=e.components,r=(0,o.A)(e,a);return(0,i.mdx)("wrapper",(0,n.A)({},p,r,{components:t,mdxType:"MDXLayout"}),(0,i.mdx)("h3",{id:"basic-tutorial"},"Basic Tutorial"),(0,i.mdx)("p",null,"The ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.0/tutorials/basic/your_first_app/simple_cli"},"Basic Tutorial")," covers basic Hydra concepts."),(0,i.mdx)("h3",{id:"structured-configs"},"Structured configs"),(0,i.mdx)("p",null,"The ",(0,i.mdx)("a",{parentName:"p",href:"/docs/1.0/tutorials/structured_config/intro"},"Structured Configs Tutorial")," shows how to create strongly typed configurations."))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/3f5d6c87.91c6a66f.js b/assets/js/3f5d6c87.91c6a66f.js deleted file mode 100644 index d90b80443f..0000000000 --- a/assets/js/3f5d6c87.91c6a66f.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[3317],{15680:(e,t,n)=>{n.r(t),n.d(t,{MDXContext:()=>d,MDXProvider:()=>m,mdx:()=>g,useMDXComponents:()=>c,withMDXComponents:()=>u});var a=n(96540);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(){return o=Object.assign||function(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var d=a.createContext({}),u=function(e){return function(t){var n=c(t.components);return a.createElement(e,o({},t,{components:n}))}},c=function(e){var t=a.useContext(d),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},m=function(e){var t=c(e.components);return a.createElement(d.Provider,{value:t},e.children)},p={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},f=a.forwardRef((function(e,t){var n=e.components,r=e.mdxType,o=e.originalType,i=e.parentName,d=s(e,["components","mdxType","originalType","parentName"]),u=c(n),m=r,f=u["".concat(i,".").concat(m)]||u[m]||p[m]||o;return n?a.createElement(f,l(l({ref:t},d),{},{components:n})):a.createElement(f,l({ref:t},d))}));function g(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var o=n.length,i=new Array(o);i[0]=f;var l={};for(var s in t)hasOwnProperty.call(t,s)&&(l[s]=t[s]);l.originalType=e,l.mdxType="string"==typeof e?e:r,i[1]=l;for(var d=2;d{n.d(t,{A:()=>s,C:()=>d});var a=n(58168),r=n(96540),o=n(75489),i=n(44586),l=n(74098);function s(e){return r.createElement(o.default,(0,a.A)({},e,{to:(t=e.to,s=(0,l.useActiveVersion)(),(0,i.default)().siteConfig.customFields.githubLinkVersionToBaseUrl[null!=(n=null==s?void 0:s.name)?n:"current"]+t),target:"_blank"}));var t,n,s}function d(e){var t,n=null!=(t=e.text)?t:"Example (Click Here)";return r.createElement(s,e,r.createElement("span",null,"\xa0"),r.createElement("img",{src:"https://img.shields.io/badge/-"+n+"-informational",alt:"Example (Click Here)"}))}},74552:(e,t,n)=>{n.r(t),n.d(t,{contentTitle:()=>d,default:()=>p,frontMatter:()=>s,metadata:()=>u,toc:()=>c});var a=n(58168),r=n(98587),o=(n(96540),n(15680)),i=n(49595),l=["components"],s={id:"defaults",title:"Defaults List"},d=void 0,u={unversionedId:"tutorials/structured_config/defaults",id:"version-1.3/tutorials/structured_config/defaults",title:"Defaults List",description:"You can define a defaults list in your primary Structured Config just like you can in your primary config.yaml file.",source:"@site/versioned_docs/version-1.3/tutorials/structured_config/4_defaults.md",sourceDirName:"tutorials/structured_config",slug:"/tutorials/structured_config/defaults",permalink:"/docs/1.3/tutorials/structured_config/defaults",editUrl:"https://github.com/facebookresearch/hydra/edit/main/website/versioned_docs/version-1.3/tutorials/structured_config/4_defaults.md",tags:[],version:"1.3",lastUpdatedBy:"Shicong Huang",lastUpdatedAt:1726678118,formattedLastUpdatedAt:"9/18/2024",sidebarPosition:4,frontMatter:{id:"defaults",title:"Defaults List"},sidebar:"docs",previous:{title:"Config Groups",permalink:"/docs/1.3/tutorials/structured_config/config_groups"},next:{title:"Structured Config schema",permalink:"/docs/1.3/tutorials/structured_config/schema"}},c=[{value:"A Note about composition order",id:"a-note-about-composition-order",children:[],level:3},{value:"Requiring users to specify a default list value",id:"requiring-users-to-specify-a-default-list-value",children:[],level:3}],m={toc:c};function p(e){var t=e.components,n=(0,r.A)(e,l);return(0,o.mdx)("wrapper",(0,a.A)({},m,n,{components:t,mdxType:"MDXLayout"}),(0,o.mdx)(i.C,{to:"examples/tutorials/structured_configs/4_defaults/my_app.py",mdxType:"ExampleGithubLink"}),(0,o.mdx)("p",null,"You can define a defaults list in your primary Structured Config just like you can in your primary ",(0,o.mdx)("inlineCode",{parentName:"p"},"config.yaml")," file.\nThe example below extends the previous example by adding a defaults list that will load ",(0,o.mdx)("inlineCode",{parentName:"p"},"db=mysql")," by default."),(0,o.mdx)("div",{class:"alert alert--info",role:"alert"},"NOTE: You can still place your defaults list in your primary (YAML) config file (Example in next page)."),(0,o.mdx)("br",null),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:"{11-14,19,25}","{11-14,19,25}":!0},'from dataclasses import dataclass\n\nimport hydra\nfrom hydra.core.config_store import ConfigStore\nfrom omegaconf import MISSING, OmegaConf\n\n@dataclass\nclass MySQLConfig:\n ...\n\n@dataclass\nclass PostGreSQLConfig:\n ...\n\ndefaults = [\n # Load the config "mysql" from the config group "db"\n {"db": "mysql"}\n]\n\n@dataclass\nclass Config:\n # this is unfortunately verbose due to @dataclass limitations\n defaults: List[Any] = field(default_factory=lambda: defaults)\n\n # Hydra will populate this field based on the defaults list\n db: Any = MISSING\n\ncs = ConfigStore.instance()\ncs.store(group="db", name="mysql", node=MySQLConfig)\ncs.store(group="db", name="postgresql", node=PostGreSQLConfig)\ncs.store(name="config", node=Config)\n\n\n@hydra.main(version_base=None, config_name="config")\ndef my_app(cfg: Config) -> None:\n print(OmegaConf.to_yaml(cfg))\n\n\nif __name__ == "__main__":\n my_app()\n')),(0,o.mdx)("p",null,"Running ",(0,o.mdx)("inlineCode",{parentName:"p"},"my_app.py")," loads the mysql config option by default:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py\ndb:\n driver: mysql\n ...\n")),(0,o.mdx)("p",null,"You can override the default option via the command line:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-yaml"},"$ python my_app.py db=postgresql\ndb:\n driver: postgresql\n ...\n")),(0,o.mdx)("h3",{id:"a-note-about-composition-order"},"A Note about composition order"),(0,o.mdx)("p",null,"The default composition order in Hydra is that values defined in a config are merged into values introduced from configs in the Defaults List - or in other words - overriding them.\nThis behavior can be unintuitive when your primary config is a Structured Config, like in the example above.\nFor example, if the primary config is:"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:"{6}","{6}":!0},'@dataclass\nclass Config:\n defaults: List[Any] = field(default_factory=lambda: [\n "debug/activate",\n # If you do not specify _self_, it will be appended to the end of the defaults list by default.\n "_self_"\n ])\n\n debug: bool = False\n')),(0,o.mdx)("p",null,"And ",(0,o.mdx)("inlineCode",{parentName:"p"},"debug/activate.yaml")," is overriding the ",(0,o.mdx)("inlineCode",{parentName:"p"},"debug")," flag to ",(0,o.mdx)("inlineCode",{parentName:"p"},"True"),", the composition order would be such that debug ends up being ",(0,o.mdx)("inlineCode",{parentName:"p"},"False"),".",(0,o.mdx)("br",{parentName:"p"}),"\n","To get ",(0,o.mdx)("inlineCode",{parentName:"p"},"debug/activate.yaml")," to override this config, explicitly specify ",(0,o.mdx)("inlineCode",{parentName:"p"},"_self_")," before ",(0,o.mdx)("inlineCode",{parentName:"p"},"debug/activate.yaml"),":"),(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:"{4}","{4}":!0},'@dataclass\nclass Config:\n defaults: List[Any] = field(default_factory=lambda: [\n "_self_",\n "debug/activate",\n ])\n\n debug: bool = False\n')),(0,o.mdx)("p",null,"See ",(0,o.mdx)("a",{parentName:"p",href:"/docs/1.3/advanced/defaults_list#composition-order"},"Composition Order")," for more information."),(0,o.mdx)("h3",{id:"requiring-users-to-specify-a-default-list-value"},"Requiring users to specify a default list value"),(0,o.mdx)("p",null,"Set ",(0,o.mdx)("inlineCode",{parentName:"p"},"db")," as ",(0,o.mdx)("inlineCode",{parentName:"p"},"MISSING")," to require the user to specify a value on the command line."),(0,o.mdx)("div",{className:"row"},(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-python",metastring:'title="Defaults list with a missing db"',title:'"Defaults',list:!0,with:!0,a:!0,missing:!0,'db"':!0},'defaults = [\n {"db": MISSING}\n]\n\n\n'))),(0,o.mdx)("div",{className:"col col--6"},(0,o.mdx)("pre",null,(0,o.mdx)("code",{parentName:"pre",className:"language-text",metastring:'title="Output"',title:'"Output"'},"$ python my_app.py\nYou must specify 'db', e.g, db=