diff --git a/404.html b/404.html index 2766a5c..a371c64 100644 --- a/404.html +++ b/404.html @@ -6,13 +6,13 @@ Page Not Found | Badger - +
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/5e2ad779.40c49abb.js b/assets/js/5e2ad779.40c49abb.js deleted file mode 100644 index 32deeba..0000000 --- a/assets/js/5e2ad779.40c49abb.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkbadger_home=self.webpackChunkbadger_home||[]).push([[61],{8555:function(e,t,i){i.r(t),i.d(t,{frontMatter:function(){return n},contentTitle:function(){return o},metadata:function(){return g},toc:function(){return d},default:function(){return p}});var s=i(7462),u=i(3366),r=(i(7294),i(3905)),a=["components"],n={sidebar_position:3},o="GUI Usage",g={unversionedId:"guides/gui-usage",id:"guides/gui-usage",isDocsHomePage:!1,title:"GUI Usage",description:"Pass",source:"@site/docs/guides/gui-usage.md",sourceDirName:"guides",slug:"/guides/gui-usage",permalink:"/Badger/docs/guides/gui-usage",editUrl:"https://github.com/SLAC-ML/Badger-Home/edit/master/docs/guides/gui-usage.md",tags:[],version:"current",sidebarPosition:3,frontMatter:{sidebar_position:3},sidebar:"tutorialSidebar",previous:{title:"CLI Usage",permalink:"/Badger/docs/guides/cli-usage"},next:{title:"Create a plugin",permalink:"/Badger/docs/guides/create-a-plugin"}},d=[],c={toc:d};function p(e){var t=e.components,i=(0,u.Z)(e,a);return(0,r.kt)("wrapper",(0,s.Z)({},c,i,{components:t,mdxType:"MDXLayout"}),(0,r.kt)("h1",{id:"gui-usage"},"GUI Usage"),(0,r.kt)("p",null,"Pass"))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/5e2ad779.5d0ffce7.js b/assets/js/5e2ad779.5d0ffce7.js new file mode 100644 index 0000000..ca1a15d --- /dev/null +++ b/assets/js/5e2ad779.5d0ffce7.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkbadger_home=self.webpackChunkbadger_home||[]).push([[61],{8555:function(e,t,i){i.r(t),i.d(t,{frontMatter:function(){return a},contentTitle:function(){return o},metadata:function(){return g},toc:function(){return d},default:function(){return p}});var s=i(7462),u=i(3366),r=(i(7294),i(3905)),n=["components"],a={sidebar_position:3},o="GUI Usage",g={unversionedId:"guides/gui-usage",id:"guides/gui-usage",isDocsHomePage:!1,title:"GUI Usage",description:"WIP",source:"@site/docs/guides/gui-usage.md",sourceDirName:"guides",slug:"/guides/gui-usage",permalink:"/Badger/docs/guides/gui-usage",editUrl:"https://github.com/SLAC-ML/Badger-Home/edit/master/docs/guides/gui-usage.md",tags:[],version:"current",sidebarPosition:3,frontMatter:{sidebar_position:3},sidebar:"tutorialSidebar",previous:{title:"CLI Usage",permalink:"/Badger/docs/guides/cli-usage"},next:{title:"Create a plugin",permalink:"/Badger/docs/guides/create-a-plugin"}},d=[],c={toc:d};function p(e){var t=e.components,i=(0,u.Z)(e,n);return(0,r.kt)("wrapper",(0,s.Z)({},c,i,{components:t,mdxType:"MDXLayout"}),(0,r.kt)("h1",{id:"gui-usage"},"GUI Usage"),(0,r.kt)("p",null,(0,r.kt)("strong",{parentName:"p"},"WIP")))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/a2b18811.5c11f824.js b/assets/js/a2b18811.5c11f824.js new file mode 100644 index 0000000..74a64f8 --- /dev/null +++ b/assets/js/a2b18811.5c11f824.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkbadger_home=self.webpackChunkbadger_home||[]).push([[288],{9409:function(e,n,a){a.r(n),a.d(n,{frontMatter:function(){return r},contentTitle:function(){return s},metadata:function(){return p},toc:function(){return d},default:function(){return m}});var t=a(7462),l=a(3366),i=(a(7294),a(3905)),o=["components"],r={sidebar_position:2},s="CLI Usage",p={unversionedId:"guides/cli-usage",id:"guides/cli-usage",isDocsHomePage:!1,title:"CLI Usage",description:"For all the implemented and planned CLI usage, please refer to these slides. We'll highlight several common CLI use cases of Badger in the following sections.",source:"@site/docs/guides/cli-usage.md",sourceDirName:"guides",slug:"/guides/cli-usage",permalink:"/Badger/docs/guides/cli-usage",editUrl:"https://github.com/SLAC-ML/Badger-Home/edit/master/docs/guides/cli-usage.md",tags:[],version:"current",sidebarPosition:2,frontMatter:{sidebar_position:2},sidebar:"tutorialSidebar",previous:{title:"API Usage",permalink:"/Badger/docs/guides/api-usage"},next:{title:"GUI Usage",permalink:"/Badger/docs/guides/gui-usage"}},d=[{value:"Get help",id:"get-help",children:[],level:2},{value:"Show metadata of Badger",id:"show-metadata-of-badger",children:[],level:2},{value:"Get information of the algorithms",id:"get-information-of-the-algorithms",children:[],level:2},{value:"Get information of the environments",id:"get-information-of-the-environments",children:[],level:2},{value:"Run and save an optimization",id:"run-and-save-an-optimization",children:[{value:"A simplest run command",id:"a-simplest-run-command",children:[],level:3},{value:"Run without confirmation",id:"run-without-confirmation",children:[],level:3},{value:"Change verbose level",id:"change-verbose-level",children:[],level:3},{value:"Configure algorithm/environment parameters",id:"configure-algorithmenvironment-parameters",children:[],level:3},{value:"Run with algorithms provided by extensions",id:"run-with-algorithms-provided-by-extensions",children:[],level:3},{value:"Save a run",id:"save-a-run",children:[],level:3}],level:2},{value:"Rerun a saved optimization routine",id:"rerun-a-saved-optimization-routine",children:[],level:2},{value:"Configure Badger",id:"configure-badger",children:[],level:2},{value:"Launch the Badger GUI",id:"launch-the-badger-gui",children:[],level:2}],u={toc:d};function m(e){var n=e.components,a=(0,l.Z)(e,o);return(0,i.kt)("wrapper",(0,t.Z)({},u,a,{components:n,mdxType:"MDXLayout"}),(0,i.kt)("h1",{id:"cli-usage"},"CLI Usage"),(0,i.kt)("p",null,"For all the implemented and planned CLI usage, please refer to ",(0,i.kt)("a",{parentName:"p",href:"https://docs.google.com/presentation/d/1APlLgaRik2VPGL7FuxEUmwHvx6egTeIRaxBKGS1TnsE/edit#slide=id.ge68b2a5657_0_5"},"these slides"),". We'll highlight several common CLI use cases of Badger in the following sections."),(0,i.kt)("h2",{id:"get-help"},"Get help"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"badger -h\n")),(0,i.kt)("p",null,"Or ",(0,i.kt)("a",{parentName:"p",href:"mailto:zhezhang@slac.stanford.edu"},"shoot me an email"),"!"),(0,i.kt)("h2",{id:"show-metadata-of-badger"},"Show metadata of Badger"),(0,i.kt)("p",null,"To show the version number and some other metadata such as plugin directory:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"badger\n")),(0,i.kt)("h2",{id:"get-information-of-the-algorithms"},"Get information of the algorithms"),(0,i.kt)("p",null,"List all the available algorithms:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"badger algo\n")),(0,i.kt)("p",null,"Get the configs of a specific algorithm:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"badger algo ALGO_NAME\n")),(0,i.kt)("p",null,"You'll get something like:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-yaml"},"name: silly\nversion: '0.1'\ndependencies:\n - numpy\nparams:\n dimension: 1\n max_iter: 42\n")),(0,i.kt)("p",null,"Note that in order to use this plugin, you'll need to install the dependencies listed in the command output. This dependency installation will be handled automatically if the plugin was installed through the ",(0,i.kt)("inlineCode",{parentName:"p"},"badger install")," command, but that command is not available yet (it is coming soon)."),(0,i.kt)("p",null,"The ",(0,i.kt)("inlineCode",{parentName:"p"},"params")," part shows all the intrinsic parameters that can be tuned when doing optimization with this algorithm."),(0,i.kt)("h2",{id:"get-information-of-the-environments"},"Get information of the environments"),(0,i.kt)("p",null,"List all the available environments:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"badger env\n")),(0,i.kt)("p",null,"Get the configs of a specific environment:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"badger env ENV_NAME\n")),(0,i.kt)("p",null,"The command will print out something like:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-yaml"},"name: dumb\nversion: '0.1'\ndependencies:\n - numpy\n - badger-opt\ninterface:\n - silly\nenvironments:\n - silly\n - naive\nparams: null\nvariables:\n - q1: 0 -> 1\n - q2: 0 -> 1\n - q3: 0 -> 1\n - q4: 0 -> 1\n - s1: 0 -> 1\n - s2: 0 -> 1\nobservations:\n - l2\n - mean\n - l2_x_mean\n")),(0,i.kt)("p",null,"There are several important properties here:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"variables"),": The tunable variables provided by this environment. You could choose a subset of the variables as the desicion variables for the optimization in the routine config. The allowed ranges (in this case, 0 to 1) are shown behind the corresponding variable names"),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"observations"),": The measurements provided by this environment. You could choose some observations as the objectives, and some other observations as the constraints in the routine config")),(0,i.kt)("h2",{id:"run-and-save-an-optimization"},"Run and save an optimization"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"badger run [-h] -a ALGO_NAME [-ap ALGO_PARAMS] -e ENV_NAME [-ep ENV_PARAMS] -c ROUTINE_CONFIG [-s [SAVE_NAME]] [-y] [-v [{0,1,2}]]\n")),(0,i.kt)("p",null,"The ",(0,i.kt)("inlineCode",{parentName:"p"},"-ap")," and ",(0,i.kt)("inlineCode",{parentName:"p"},"-ep")," optional arguments, and the ",(0,i.kt)("inlineCode",{parentName:"p"},"-c")," argument accept either a ",(0,i.kt)("inlineCode",{parentName:"p"},".yaml")," file path or a yaml string. The configs set to ",(0,i.kt)("inlineCode",{parentName:"p"},"-ap")," and ",(0,i.kt)("inlineCode",{parentName:"p"},"-ep"),' optional arguments should be treated as "patch" on the default algorithm and environment parameters, respectively, which means that you only need to specify the paramters that you\'d like to change on top of the default configs, rather than pass in a full config. The content of the ',(0,i.kt)("inlineCode",{parentName:"p"},"ROUTINE_CONFIG")," (aka routine configs) should look like this:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-yaml"},"variables:\n - x1: [-1, 0.5]\n - x2\nobjectives:\n - c1\n - y2: MINIMIZE\nconstraints:\n - y1:\n - GREATER_THAN\n - 0\n - c2:\n - LESS_THAN\n - 0.5\n")),(0,i.kt)("p",null,"The ",(0,i.kt)("inlineCode",{parentName:"p"},"variables")," and ",(0,i.kt)("inlineCode",{parentName:"p"},"objectives")," properties are required, while the ",(0,i.kt)("inlineCode",{parentName:"p"},"constraints")," property is optional. Just omit the ",(0,i.kt)("inlineCode",{parentName:"p"},"constraints")," property if there are no constraints for your optimization problem. The names listed in ",(0,i.kt)("inlineCode",{parentName:"p"},"variables")," should come from ",(0,i.kt)("inlineCode",{parentName:"p"},"variables")," of the env specified by the ",(0,i.kt)("inlineCode",{parentName:"p"},"-e")," argument, while the names listed in ",(0,i.kt)("inlineCode",{parentName:"p"},"objectives")," and ",(0,i.kt)("inlineCode",{parentName:"p"},"constraints")," should come from ",(0,i.kt)("inlineCode",{parentName:"p"},"observations")," of that env."),(0,i.kt)("p",null,"All optimization runs will be archived in the ",(0,i.kt)("inlineCode",{parentName:"p"},"$BADGER_ARCHIVE_ROOT")," folder that you initially set up when running ",(0,i.kt)("inlineCode",{parentName:"p"},"badger")," the first time."),(0,i.kt)("p",null,"Several example routine configs can be found in the ",(0,i.kt)("inlineCode",{parentName:"p"},"examples")," folder."),(0,i.kt)("p",null,"Below are some example ",(0,i.kt)("inlineCode",{parentName:"p"},"badger run")," commands. They are assumed to run under the parent directory of the ",(0,i.kt)("inlineCode",{parentName:"p"},"examples")," folder (you'll need to clone the ",(0,i.kt)("inlineCode",{parentName:"p"},"examples")," folder from this repo to your computer first). You could run them from any directory, just remember to change the routine config path accordingly."),(0,i.kt)("h3",{id:"a-simplest-run-command"},"A simplest run command"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"badger run -a silly -e TNK -c examples/silly_tnk.yaml\n")),(0,i.kt)("h3",{id:"run-without-confirmation"},"Run without confirmation"),(0,i.kt)("p",null,"Badger will let you confirm the routine before running it. You could skip the confirmation by adding the ",(0,i.kt)("inlineCode",{parentName:"p"},"-y")," option:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"badger run -a silly -e TNK -c examples/silly_tnk.yaml -y\n")),(0,i.kt)("h3",{id:"change-verbose-level"},"Change verbose level"),(0,i.kt)("p",null,"By default, Badger will print out a table contains all the evaluated solutions along the optimization run (with the optimal ones highlighted), you could alter the default behavior by setting the ",(0,i.kt)("inlineCode",{parentName:"p"},"-v")," option."),(0,i.kt)("p",null,"The default verbose level 2 will print out all the solutions:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"badger run -a silly -e TNK -c examples/silly_tnk.yaml -v 2\n")),(0,i.kt)("p",null,"The table would look like:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre"},"| iter | c1 | x2 |\n----------------------------------------\n| 1 | 3.73 | 2.198 |\n| 2 | -0.9861 | 0.3375 |\n| 3 | 1.888 | 1.729 |\n| 4 | 2.723 | 1.955 |\n| 5 | -1.092 | 0.08923 |\n| 6 | 1.357 | 1.568 |\n| 7 | 4.559 | 2.379 |\n| 8 | 8.757 | 3.14 |\n| 9 | 2.957 | 2.014 |\n| 10 | 0.1204 | 1.105 |\n| 11 | 2.516 | 1.902 |\n| 12 | -0.01194 | 1.043 |\n| 13 | 7.953 | 3.009 |\n| 14 | -1.095 | 0.07362 |\n| 15 | -0.3229 | 0.8815 |\n| 16 | -1.096 | 0.06666 |\n| 17 | 2.662 | 1.94 |\n| 18 | 6.987 | 2.844 |\n| 19 | -0.9734 | 0.3558 |\n| 20 | 3.694 | 2.19 |\n| 21 | -1.032 | 0.2613 |\n| 22 | 2.441 | 1.882 |\n| 23 | 7.042 | 2.853 |\n| 24 | 4.682 | 2.405 |\n| 25 | 0.5964 | 1.302 |\n| 26 | 0.3664 | 1.211 |\n| 27 | 1.966 | 1.751 |\n| 28 | 0.2181 | 1.148 |\n| 29 | 7.954 | 3.009 |\n| 30 | -0.8986 | 0.4488 |\n| 31 | -0.7536 | 0.5885 |\n| 32 | 3.602 | 2.168 |\n| 33 | 0.5527 | 1.286 |\n| 34 | -0.6969 | 0.6349 |\n| 35 | -1.094 | 0.07974 |\n| 36 | -0.8758 | 0.4735 |\n| 37 | 5.995 | 2.664 |\n| 38 | 3.638 | 2.177 |\n| 39 | 2.489 | 1.895 |\n| 40 | 0.8434 | 1.394 |\n| 41 | 0.4919 | 1.262 |\n| 42 | -0.4929 | 0.7792 |\n========================================\n")),(0,i.kt)("p",null,"Verbose level 1 only prints out the optimal solutions along the run:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"badger run -a silly -e TNK -c examples/silly_tnk.yaml -v 1\n")),(0,i.kt)("p",null,"The table would look like:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre"},"| iter | c1 | x2 |\n----------------------------------------\n| 1 | 1.96 | 1.749 |\n| 2 | -1.037 | 0.2518 |\n| 18 | -1.1 | 0.01942 |\n========================================\n")),(0,i.kt)("p",null,"Verbose level 0 turns off the printing feature completely:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"badger run -a silly -e TNK -c examples/silly_tnk.yaml -v 0\n")),(0,i.kt)("p",null,"The table would not be printed."),(0,i.kt)("h3",{id:"configure-algorithmenvironment-parameters"},"Configure algorithm/environment parameters"),(0,i.kt)("p",null,"The following two commands show how to config parameters of the algorithm/environment."),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},'badger run -a silly -ap "dimension: 4" -e dumb -c examples/silly_dumb.yaml\n')),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},'badger run -a silly -ap "{dimension: 4, max_iter: 10}" -e dumb -c examples/silly_dumb.yaml\n')),(0,i.kt)("h3",{id:"run-with-algorithms-provided-by-extensions"},"Run with algorithms provided by extensions"),(0,i.kt)("p",null,"In order to run the following command, you'll need to ",(0,i.kt)("a",{parentName:"p",href:"https://github.com/ChristopherMayes/Xopt#installing-xopt"},"set up xopt")," on your computer (since the algorithms are provided by xopt)."),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},'badger run -a cnsga -ap "max_generations: 10" -e TNK -c examples/cnsga_tnk.yaml\n')),(0,i.kt)("h3",{id:"save-a-run"},"Save a run"),(0,i.kt)("p",null,"To save a routine to database in ",(0,i.kt)("inlineCode",{parentName:"p"},"$BADGER_DB_ROOT"),", just add the ",(0,i.kt)("inlineCode",{parentName:"p"},"-s [SAVE_NAME]")," option. This command will run and save the routine with a randomly generated two-word name:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"badger run -a silly -e TNK -c examples/silly_tnk.yaml -s\n")),(0,i.kt)("p",null,"The following command will run the routine and save it as ",(0,i.kt)("inlineCode",{parentName:"p"},"test_routine"),":"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"badger run -a silly -e TNK -c examples/silly_tnk.yaml -s test_routine\n")),(0,i.kt)("h2",{id:"rerun-a-saved-optimization-routine"},"Rerun a saved optimization routine"),(0,i.kt)("p",null,"Say we have the routine ",(0,i.kt)("inlineCode",{parentName:"p"},"test_routine")," saved. List all the saved routines by:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"badger routine\n")),(0,i.kt)("p",null,"To get the details of some specific routine (say, ",(0,i.kt)("inlineCode",{parentName:"p"},"test_routine"),"):"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"badger routine test_routine\n")),(0,i.kt)("p",null,"To rerun it, do:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"badger routine test_routine -r\n")),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"badger routine")," also supports the ",(0,i.kt)("inlineCode",{parentName:"p"},"-y")," and ",(0,i.kt)("inlineCode",{parentName:"p"},"-v")," options, as ",(0,i.kt)("inlineCode",{parentName:"p"},"badger run")," does."),(0,i.kt)("h2",{id:"configure-badger"},"Configure Badger"),(0,i.kt)("p",null,"If you would like to change some setting that you configured during the first time you run ",(0,i.kt)("inlineCode",{parentName:"p"},"badger"),", you could do so with ",(0,i.kt)("inlineCode",{parentName:"p"},"badger config"),"."),(0,i.kt)("p",null,"List all the configurations:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"badger config\n")),(0,i.kt)("p",null,"To config a property:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"badger config KEY\n")),(0,i.kt)("p",null,"Where ",(0,i.kt)("inlineCode",{parentName:"p"},"KEY")," is one of the keys in the configuration list."),(0,i.kt)("h2",{id:"launch-the-badger-gui"},"Launch the Badger GUI"),(0,i.kt)("p",null,"Badger supports a GUI mode. You can launch the GUI by:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre"},"badger -g\n")))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/a2b18811.b77eb052.js b/assets/js/a2b18811.b77eb052.js deleted file mode 100644 index 4958901..0000000 --- a/assets/js/a2b18811.b77eb052.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkbadger_home=self.webpackChunkbadger_home||[]).push([[288],{9409:function(e,s,i){i.r(s),i.d(s,{frontMatter:function(){return u},contentTitle:function(){return o},metadata:function(){return d},toc:function(){return c},default:function(){return l}});var t=i(7462),a=i(3366),r=(i(7294),i(3905)),n=["components"],u={sidebar_position:2},o="CLI Usage",d={unversionedId:"guides/cli-usage",id:"guides/cli-usage",isDocsHomePage:!1,title:"CLI Usage",description:"Pass",source:"@site/docs/guides/cli-usage.md",sourceDirName:"guides",slug:"/guides/cli-usage",permalink:"/Badger/docs/guides/cli-usage",editUrl:"https://github.com/SLAC-ML/Badger-Home/edit/master/docs/guides/cli-usage.md",tags:[],version:"current",sidebarPosition:2,frontMatter:{sidebar_position:2},sidebar:"tutorialSidebar",previous:{title:"API Usage",permalink:"/Badger/docs/guides/api-usage"},next:{title:"GUI Usage",permalink:"/Badger/docs/guides/gui-usage"}},c=[],g={toc:c};function l(e){var s=e.components,i=(0,a.Z)(e,n);return(0,r.kt)("wrapper",(0,t.Z)({},g,i,{components:s,mdxType:"MDXLayout"}),(0,r.kt)("h1",{id:"cli-usage"},"CLI Usage"),(0,r.kt)("p",null,"Pass"))}l.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/e689722c.babc55c6.js b/assets/js/e689722c.babc55c6.js new file mode 100644 index 0000000..2c6a6a6 --- /dev/null +++ b/assets/js/e689722c.babc55c6.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkbadger_home=self.webpackChunkbadger_home||[]).push([[276],{3075:function(e,t,i){i.r(t),i.d(t,{frontMatter:function(){return o},contentTitle:function(){return u},metadata:function(){return d},toc:function(){return g},default:function(){return p}});var s=i(7462),a=i(3366),r=(i(7294),i(3905)),n=["components"],o={sidebar_position:1},u="API Usage",d={unversionedId:"guides/api-usage",id:"guides/api-usage",isDocsHomePage:!1,title:"API Usage",description:"WIP",source:"@site/docs/guides/api-usage.md",sourceDirName:"guides",slug:"/guides/api-usage",permalink:"/Badger/docs/guides/api-usage",editUrl:"https://github.com/SLAC-ML/Badger-Home/edit/master/docs/guides/api-usage.md",tags:[],version:"current",sidebarPosition:1,frontMatter:{sidebar_position:1},sidebar:"tutorialSidebar",previous:{title:"Tutorial",permalink:"/Badger/docs/getting-started/tutorial"},next:{title:"CLI Usage",permalink:"/Badger/docs/guides/cli-usage"}},g=[],c={toc:g};function p(e){var t=e.components,i=(0,a.Z)(e,n);return(0,r.kt)("wrapper",(0,s.Z)({},c,i,{components:t,mdxType:"MDXLayout"}),(0,r.kt)("h1",{id:"api-usage"},"API Usage"),(0,r.kt)("p",null,(0,r.kt)("strong",{parentName:"p"},"WIP")))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/e689722c.cc8f20c9.js b/assets/js/e689722c.cc8f20c9.js deleted file mode 100644 index c8cb555..0000000 --- a/assets/js/e689722c.cc8f20c9.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkbadger_home=self.webpackChunkbadger_home||[]).push([[276],{3075:function(e,t,i){i.r(t),i.d(t,{frontMatter:function(){return o},contentTitle:function(){return u},metadata:function(){return d},toc:function(){return g},default:function(){return p}});var s=i(7462),a=i(3366),r=(i(7294),i(3905)),n=["components"],o={sidebar_position:1},u="API Usage",d={unversionedId:"guides/api-usage",id:"guides/api-usage",isDocsHomePage:!1,title:"API Usage",description:"Pass",source:"@site/docs/guides/api-usage.md",sourceDirName:"guides",slug:"/guides/api-usage",permalink:"/Badger/docs/guides/api-usage",editUrl:"https://github.com/SLAC-ML/Badger-Home/edit/master/docs/guides/api-usage.md",tags:[],version:"current",sidebarPosition:1,frontMatter:{sidebar_position:1},sidebar:"tutorialSidebar",previous:{title:"Tutorial",permalink:"/Badger/docs/getting-started/tutorial"},next:{title:"CLI Usage",permalink:"/Badger/docs/guides/cli-usage"}},g=[],c={toc:g};function p(e){var t=e.components,i=(0,a.Z)(e,n);return(0,r.kt)("wrapper",(0,s.Z)({},c,i,{components:t,mdxType:"MDXLayout"}),(0,r.kt)("h1",{id:"api-usage"},"API Usage"),(0,r.kt)("p",null,"Pass"))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/runtime~main.7029217d.js b/assets/js/runtime~main.2c5deef4.js similarity index 94% rename from assets/js/runtime~main.7029217d.js rename to assets/js/runtime~main.2c5deef4.js index 588ada1..132da56 100644 --- a/assets/js/runtime~main.7029217d.js +++ b/assets/js/runtime~main.2c5deef4.js @@ -1 +1 @@ -!function(){"use strict";var e,t,n,r,o,c={},a={};function f(e){var t=a[e];if(void 0!==t)return t.exports;var n=a[e]={id:e,loaded:!1,exports:{}};return c[e].call(n.exports,n,n.exports,f),n.loaded=!0,n.exports}f.m=c,f.c=a,e=[],f.O=function(t,n,r,o){if(!n){var c=1/0;for(d=0;d=o)&&Object.keys(f.O).every((function(e){return f.O[e](n[u])}))?n.splice(u--,1):(a=!1,o0&&e[d-1][2]>o;d--)e[d]=e[d-1];e[d]=[n,r,o]},f.n=function(e){var t=e&&e.__esModule?function(){return e.default}:function(){return e};return f.d(t,{a:t}),t},n=Object.getPrototypeOf?function(e){return Object.getPrototypeOf(e)}:function(e){return e.__proto__},f.t=function(e,r){if(1&r&&(e=this(e)),8&r)return e;if("object"==typeof e&&e){if(4&r&&e.__esModule)return e;if(16&r&&"function"==typeof e.then)return e}var o=Object.create(null);f.r(o);var c={};t=t||[null,n({}),n([]),n(n)];for(var a=2&r&&e;"object"==typeof a&&!~t.indexOf(a);a=n(a))Object.getOwnPropertyNames(a).forEach((function(t){c[t]=function(){return e[t]}}));return c.default=function(){return e},f.d(o,c),o},f.d=function(e,t){for(var n in t)f.o(t,n)&&!f.o(e,n)&&Object.defineProperty(e,n,{enumerable:!0,get:t[n]})},f.f={},f.e=function(e){return Promise.all(Object.keys(f.f).reduce((function(t,n){return f.f[n](e,t),t}),[]))},f.u=function(e){return"assets/js/"+({13:"01a85c17",53:"935f2afb",61:"5e2ad779",75:"6d4920cb",89:"a6aa9e1f",103:"ccc49370",104:"db84cbea",152:"54f44165",195:"c4f5d8e4",214:"7a8ea9cb",249:"13db8233",276:"e689722c",288:"a2b18811",489:"2a19b374",514:"1be78505",535:"814f3328",592:"common",608:"9e4087bc",610:"6875c492",618:"72b80372",653:"67b9383b",659:"e3ae7939",671:"0e384e19",769:"6eada910",918:"17896441",965:"b171606d",978:"c7e3ca8c"}[e]||e)+"."+{13:"0af78e0c",53:"d2fa5544",61:"40c49abb",75:"fcbe7e19",89:"37a21e01",103:"63b3eedb",104:"f3d00777",152:"bd72746d",195:"964462aa",214:"3a552fb0",249:"5a475061",276:"cc8f20c9",288:"b77eb052",489:"a7bdca31",514:"84f0b0c2",535:"4b1b2a12",592:"914f4003",608:"6ce78891",610:"73be0d48",618:"1d60fd4f",653:"69cb3bb8",659:"5669b728",671:"5cde9241",707:"5cb9c152",769:"5341980a",814:"b54f29fc",818:"8df777da",918:"3da4c305",965:"5fe2ce0e",978:"538084c4"}[e]+".js"},f.miniCssF=function(e){return"assets/css/styles.de163cde.css"},f.g=function(){if("object"==typeof globalThis)return globalThis;try{return this||new Function("return this")()}catch(e){if("object"==typeof window)return window}}(),f.o=function(e,t){return Object.prototype.hasOwnProperty.call(e,t)},r={},o="badger-home:",f.l=function(e,t,n,c){if(r[e])r[e].push(t);else{var a,u;if(void 0!==n)for(var i=document.getElementsByTagName("script"),d=0;d=o)&&Object.keys(f.O).every((function(e){return f.O[e](n[u])}))?n.splice(u--,1):(a=!1,o0&&e[d-1][2]>o;d--)e[d]=e[d-1];e[d]=[n,r,o]},f.n=function(e){var t=e&&e.__esModule?function(){return e.default}:function(){return e};return f.d(t,{a:t}),t},n=Object.getPrototypeOf?function(e){return Object.getPrototypeOf(e)}:function(e){return e.__proto__},f.t=function(e,r){if(1&r&&(e=this(e)),8&r)return e;if("object"==typeof e&&e){if(4&r&&e.__esModule)return e;if(16&r&&"function"==typeof e.then)return e}var o=Object.create(null);f.r(o);var c={};t=t||[null,n({}),n([]),n(n)];for(var a=2&r&&e;"object"==typeof a&&!~t.indexOf(a);a=n(a))Object.getOwnPropertyNames(a).forEach((function(t){c[t]=function(){return e[t]}}));return c.default=function(){return e},f.d(o,c),o},f.d=function(e,t){for(var n in t)f.o(t,n)&&!f.o(e,n)&&Object.defineProperty(e,n,{enumerable:!0,get:t[n]})},f.f={},f.e=function(e){return Promise.all(Object.keys(f.f).reduce((function(t,n){return f.f[n](e,t),t}),[]))},f.u=function(e){return"assets/js/"+({13:"01a85c17",53:"935f2afb",61:"5e2ad779",75:"6d4920cb",89:"a6aa9e1f",103:"ccc49370",104:"db84cbea",152:"54f44165",195:"c4f5d8e4",214:"7a8ea9cb",249:"13db8233",276:"e689722c",288:"a2b18811",489:"2a19b374",514:"1be78505",535:"814f3328",592:"common",608:"9e4087bc",610:"6875c492",618:"72b80372",653:"67b9383b",659:"e3ae7939",671:"0e384e19",769:"6eada910",918:"17896441",965:"b171606d",978:"c7e3ca8c"}[e]||e)+"."+{13:"0af78e0c",53:"d2fa5544",61:"5d0ffce7",75:"fcbe7e19",89:"37a21e01",103:"63b3eedb",104:"f3d00777",152:"bd72746d",195:"964462aa",214:"3a552fb0",249:"5a475061",276:"babc55c6",288:"5c11f824",489:"a7bdca31",514:"84f0b0c2",535:"4b1b2a12",592:"914f4003",608:"6ce78891",610:"73be0d48",618:"1d60fd4f",653:"69cb3bb8",659:"5669b728",671:"5cde9241",707:"5cb9c152",769:"5341980a",814:"b54f29fc",818:"8df777da",918:"3da4c305",965:"5fe2ce0e",978:"538084c4"}[e]+".js"},f.miniCssF=function(e){return"assets/css/styles.de163cde.css"},f.g=function(){if("object"==typeof globalThis)return globalThis;try{return this||new Function("return this")()}catch(e){if("object"==typeof window)return window}}(),f.o=function(e,t){return Object.prototype.hasOwnProperty.call(e,t)},r={},o="badger-home:",f.l=function(e,t,n,c){if(r[e])r[e].push(t);else{var a,u;if(void 0!==n)for(var i=document.getElementsByTagName("script"),d=0;d Blog | Badger - +
- + \ No newline at end of file diff --git a/blog/archive.html b/blog/archive.html index 4e173ed..cb66501 100644 --- a/blog/archive.html +++ b/blog/archive.html @@ -6,13 +6,13 @@ Archive | Badger - +

Archive

Archive

2021

- + \ No newline at end of file diff --git a/blog/tags.html b/blog/tags.html index 9ed6c26..206f163 100644 --- a/blog/tags.html +++ b/blog/tags.html @@ -6,13 +6,13 @@ Tags | Badger - +

Tags

- + \ No newline at end of file diff --git a/blog/tags/badger.html b/blog/tags/badger.html index 983b1bc..893bd9a 100644 --- a/blog/tags/badger.html +++ b/blog/tags/badger.html @@ -6,13 +6,13 @@ One post tagged with "badger" | Badger - +

One post tagged with "badger"

View All Tags
- + \ No newline at end of file diff --git a/blog/tags/hello.html b/blog/tags/hello.html index e54b0ee..0a11d20 100644 --- a/blog/tags/hello.html +++ b/blog/tags/hello.html @@ -6,13 +6,13 @@ One post tagged with "hello" | Badger - +

One post tagged with "hello"

View All Tags
- + \ No newline at end of file diff --git a/blog/tags/slac.html b/blog/tags/slac.html index ca1d33a..01df757 100644 --- a/blog/tags/slac.html +++ b/blog/tags/slac.html @@ -6,13 +6,13 @@ One post tagged with "SLAC" | Badger - +

One post tagged with "SLAC"

View All Tags
- + \ No newline at end of file diff --git a/blog/welcome.html b/blog/welcome.html index 5befdd8..6545c87 100644 --- a/blog/welcome.html +++ b/blog/welcome.html @@ -6,13 +6,13 @@ Welcome | Badger - +
- + \ No newline at end of file diff --git a/docs/getting-started/installation.html b/docs/getting-started/installation.html index 909d1f8..c5d0dd7 100644 --- a/docs/getting-started/installation.html +++ b/docs/getting-started/installation.html @@ -6,13 +6,13 @@ Installation | Badger - +

Installation

Badger is essentially a python package. It's recommended to install and test it in a separate python virtual environment before using it in a production env.

Requirements

  • Python version >= 3.6. Python 3.7 is recommended

Install core package

Badger has a core package (badger-opt) that can be extended by a set of plugins. Badger core package is available on both pip and conda. So you could install Badger with:

pip install badger-opt

Or

conda install -c conda-forge badger-opt

Install sample plugins

Clone the badger plugins repo to some directory on your computer:

git clone https://github.com/SLAC-ML/Badger-Plugins.git

Set up Badger

Once badger-opt is installed and you have the badger plugins ready, run the following command:

badger

Follow the instructions and configure several paths that are needed by Badger.

- + \ No newline at end of file diff --git a/docs/getting-started/tutorial.html b/docs/getting-started/tutorial.html index fac0013..675357d 100644 --- a/docs/getting-started/tutorial.html +++ b/docs/getting-started/tutorial.html @@ -6,7 +6,7 @@ Tutorial | Badger - + @@ -16,7 +16,7 @@ optimal means minimal c1) at the evaluation time are highlighted.

In the example above, we use the silly algorithm (which is just a random search algorithm) to optimize the TNK environment, as shown in the reviewed routine. Environment TNK has 2 variables and 5 observations:

TNK environment
name: TNK
version: '0.1'
dependencies:
  - numpy
params: null
variables:
  - x1: 0 -> 3.14159
  - x2: 0 -> 3.14159
observations:
  - y1
  - y2
  - c1
  - c2
  - some_array

We specify in the config.yaml that we would like to tune varaible x2, and minimize observation c1 of environment TNK as objective. The configuration that could reproduce the whole optimization setup is called a routine in Badger. A routine contains the information of the algorithm, the environment, and the config of the optimization (the variables, the objectives, and the constraints).

We just saved the routine of the run as helloworld. Now you could view the routine again by:

badger routine helloworld

Re-run an optimization

We can re-run a saved routine in Badger. Let's re-run the helloworld routine that we just saved:

badger routine helloworld -r

Badger would behave exactly the same way as the first time you run the routine.

View the historical optimization data

You can cd to the Badger archive root (the one you setup during the initial configurations) and view the historical optimization data. The file structure is a tree-like one, with year, year-month, year-month-day as the first 3 levels of branches, and the optimization runs as leaves:

Badger archive root file structure
|--2021
    |--2021-11
        |--2021-11-24
            |--BadgerOpt-2021-11-24-133007.yaml
            |--BadgerOpt-2021-11-24-113241.yaml
            |--...
        |--...
    |--...
|--...

The yaml data file contains the routine information and the solutions evaluated during the run. The content would look like this:

BadgerOpt-2021-11-24-133007.yaml
routine:
  name: helloworld
  algo: silly
  env: TNK
  algo_params:
    dimension: 1
    max_iter: 10
  env_params: null
  config:
    variables:
      - x2:
          - 0.0
          - 3.1416
    objectives:
      - c1: MINIMIZE
    constraints: null
data:
  timestamp:
    - 24-Nov-2021 13:30:06
    - 24-Nov-2021 13:30:06
    - 24-Nov-2021 13:30:06
    - 24-Nov-2021 13:30:06
    - 24-Nov-2021 13:30:06
    - 24-Nov-2021 13:30:06
    - 24-Nov-2021 13:30:06
    - 24-Nov-2021 13:30:07
    - 24-Nov-2021 13:30:07
    - 24-Nov-2021 13:30:07
  c1:
    - 2.093905436806936
    - 2.6185501712620036
    - -0.8170601778601619
    - 7.869183841178197
    - -1.0945113202011
    - 0.514833333947652
    - -1.0331173238615994
    - 1.4523371516674013
    - 1.3610274948700156
    - -0.0042273815683477045
  x2:
    - 1.78715008793524
    - 1.9283542649788197
    - 0.5319208795862764
    - 2.9948595695254556
    - 0.07408562477903413
    - 1.2707609271407632
    - 0.2586168520000207
    - 1.5976035652399507
    - 1.5687662333407153
    - 1.0467915830917118

Create a simple environment

Now let's create a simple Badger environment and run optimization on it.

- + \ No newline at end of file diff --git a/docs/guides/api-usage.html b/docs/guides/api-usage.html index a6e27fb..377ea47 100644 --- a/docs/guides/api-usage.html +++ b/docs/guides/api-usage.html @@ -5,14 +5,14 @@ -API Usage | Badger - +API Usage | Badger +
-
- +
+ \ No newline at end of file diff --git a/docs/guides/cli-usage.html b/docs/guides/cli-usage.html index fe22864..e57f3e0 100644 --- a/docs/guides/cli-usage.html +++ b/docs/guides/cli-usage.html @@ -5,14 +5,14 @@ -CLI Usage | Badger - +CLI Usage | Badger +
-
- +

CLI Usage

For all the implemented and planned CLI usage, please refer to these slides. We'll highlight several common CLI use cases of Badger in the following sections.

Get help

badger -h

Or shoot me an email!

Show metadata of Badger

To show the version number and some other metadata such as plugin directory:

badger

Get information of the algorithms

List all the available algorithms:

badger algo

Get the configs of a specific algorithm:

badger algo ALGO_NAME

You'll get something like:

name: silly
version: '0.1'
dependencies:
  - numpy
params:
  dimension: 1
  max_iter: 42

Note that in order to use this plugin, you'll need to install the dependencies listed in the command output. This dependency installation will be handled automatically if the plugin was installed through the badger install command, but that command is not available yet (it is coming soon).

The params part shows all the intrinsic parameters that can be tuned when doing optimization with this algorithm.

Get information of the environments

List all the available environments:

badger env

Get the configs of a specific environment:

badger env ENV_NAME

The command will print out something like:

name: dumb
version: '0.1'
dependencies:
  - numpy
  - badger-opt
interface:
  - silly
environments:
  - silly
  - naive
params: null
variables:
  - q1: 0 -> 1
  - q2: 0 -> 1
  - q3: 0 -> 1
  - q4: 0 -> 1
  - s1: 0 -> 1
  - s2: 0 -> 1
observations:
  - l2
  - mean
  - l2_x_mean

There are several important properties here:

  • variables: The tunable variables provided by this environment. You could choose a subset of the variables as the desicion variables for the optimization in the routine config. The allowed ranges (in this case, 0 to 1) are shown behind the corresponding variable names
  • observations: The measurements provided by this environment. You could choose some observations as the objectives, and some other observations as the constraints in the routine config

Run and save an optimization

badger run [-h] -a ALGO_NAME [-ap ALGO_PARAMS] -e ENV_NAME [-ep ENV_PARAMS] -c ROUTINE_CONFIG [-s [SAVE_NAME]] [-y] [-v [{0,1,2}]]

The -ap and -ep optional arguments, and the -c argument accept either a .yaml file path or a yaml string. The configs set to -ap and -ep optional arguments should be treated as "patch" on the default algorithm and environment parameters, respectively, which means that you only need to specify the paramters that you'd like to change on top of the default configs, rather than pass in a full config. The content of the ROUTINE_CONFIG (aka routine configs) should look like this:

variables:
  - x1: [-1, 0.5]
  - x2
objectives:
  - c1
  - y2: MINIMIZE
constraints:
  - y1:
      - GREATER_THAN
      - 0
  - c2:
      - LESS_THAN
      - 0.5

The variables and objectives properties are required, while the constraints property is optional. Just omit the constraints property if there are no constraints for your optimization problem. The names listed in variables should come from variables of the env specified by the -e argument, while the names listed in objectives and constraints should come from observations of that env.

All optimization runs will be archived in the $BADGER_ARCHIVE_ROOT folder that you initially set up when running badger the first time.

Several example routine configs can be found in the examples folder.

Below are some example badger run commands. They are assumed to run under the parent directory of the examples folder (you'll need to clone the examples folder from this repo to your computer first). You could run them from any directory, just remember to change the routine config path accordingly.

A simplest run command

badger run -a silly -e TNK -c examples/silly_tnk.yaml

Run without confirmation

Badger will let you confirm the routine before running it. You could skip the confirmation by adding the -y option:

badger run -a silly -e TNK -c examples/silly_tnk.yaml -y

Change verbose level

By default, Badger will print out a table contains all the evaluated solutions along the optimization run (with the optimal ones highlighted), you could alter the default behavior by setting the -v option.

The default verbose level 2 will print out all the solutions:

badger run -a silly -e TNK -c examples/silly_tnk.yaml -v 2

The table would look like:

|    iter    |     c1     |     x2     |
----------------------------------------
|  1         |  3.73      |  2.198     |
|  2         | -0.9861    |  0.3375    |
|  3         |  1.888     |  1.729     |
|  4         |  2.723     |  1.955     |
|  5         | -1.092     |  0.08923   |
|  6         |  1.357     |  1.568     |
|  7         |  4.559     |  2.379     |
|  8         |  8.757     |  3.14      |
|  9         |  2.957     |  2.014     |
|  10        |  0.1204    |  1.105     |
|  11        |  2.516     |  1.902     |
|  12        | -0.01194   |  1.043     |
|  13        |  7.953     |  3.009     |
|  14        | -1.095     |  0.07362   |
|  15        | -0.3229    |  0.8815    |
|  16        | -1.096     |  0.06666   |
|  17        |  2.662     |  1.94      |
|  18        |  6.987     |  2.844     |
|  19        | -0.9734    |  0.3558    |
|  20        |  3.694     |  2.19      |
|  21        | -1.032     |  0.2613    |
|  22        |  2.441     |  1.882     |
|  23        |  7.042     |  2.853     |
|  24        |  4.682     |  2.405     |
|  25        |  0.5964    |  1.302     |
|  26        |  0.3664    |  1.211     |
|  27        |  1.966     |  1.751     |
|  28        |  0.2181    |  1.148     |
|  29        |  7.954     |  3.009     |
|  30        | -0.8986    |  0.4488    |
|  31        | -0.7536    |  0.5885    |
|  32        |  3.602     |  2.168     |
|  33        |  0.5527    |  1.286     |
|  34        | -0.6969    |  0.6349    |
|  35        | -1.094     |  0.07974   |
|  36        | -0.8758    |  0.4735    |
|  37        |  5.995     |  2.664     |
|  38        |  3.638     |  2.177     |
|  39        |  2.489     |  1.895     |
|  40        |  0.8434    |  1.394     |
|  41        |  0.4919    |  1.262     |
|  42        | -0.4929    |  0.7792    |
========================================

Verbose level 1 only prints out the optimal solutions along the run:

badger run -a silly -e TNK -c examples/silly_tnk.yaml -v 1

The table would look like:

|    iter    |     c1     |     x2     |
----------------------------------------
|  1         |  1.96      |  1.749     |
|  2         | -1.037     |  0.2518    |
|  18        | -1.1       |  0.01942   |
========================================

Verbose level 0 turns off the printing feature completely:

badger run -a silly -e TNK -c examples/silly_tnk.yaml -v 0

The table would not be printed.

Configure algorithm/environment parameters

The following two commands show how to config parameters of the algorithm/environment.

badger run -a silly -ap "dimension: 4" -e dumb -c examples/silly_dumb.yaml
badger run -a silly -ap "{dimension: 4, max_iter: 10}" -e dumb -c examples/silly_dumb.yaml

Run with algorithms provided by extensions

In order to run the following command, you'll need to set up xopt on your computer (since the algorithms are provided by xopt).

badger run -a cnsga -ap "max_generations: 10" -e TNK -c examples/cnsga_tnk.yaml

Save a run

To save a routine to database in $BADGER_DB_ROOT, just add the -s [SAVE_NAME] option. This command will run and save the routine with a randomly generated two-word name:

badger run -a silly -e TNK -c examples/silly_tnk.yaml -s

The following command will run the routine and save it as test_routine:

badger run -a silly -e TNK -c examples/silly_tnk.yaml -s test_routine

Rerun a saved optimization routine

Say we have the routine test_routine saved. List all the saved routines by:

badger routine

To get the details of some specific routine (say, test_routine):

badger routine test_routine

To rerun it, do:

badger routine test_routine -r

badger routine also supports the -y and -v options, as badger run does.

Configure Badger

If you would like to change some setting that you configured during the first time you run badger, you could do so with badger config.

List all the configurations:

badger config

To config a property:

badger config KEY

Where KEY is one of the keys in the configuration list.

Launch the Badger GUI

Badger supports a GUI mode. You can launch the GUI by:

badger -g
+ \ No newline at end of file diff --git a/docs/guides/create-a-plugin.html b/docs/guides/create-a-plugin.html index b06c180..546d633 100644 --- a/docs/guides/create-a-plugin.html +++ b/docs/guides/create-a-plugin.html @@ -6,13 +6,13 @@ Create a plugin | Badger - +

Create a plugin

Plugins have three types:

  • Algorithm: function
  • Interface: class
  • Environment: class

Create an algorithm plugin

Create an interface plugin

Create an environment plugin

- + \ No newline at end of file diff --git a/docs/guides/gui-usage.html b/docs/guides/gui-usage.html index 3756392..b558ed0 100644 --- a/docs/guides/gui-usage.html +++ b/docs/guides/gui-usage.html @@ -5,14 +5,14 @@ -GUI Usage | Badger - +GUI Usage | Badger +
-
- +
+ \ No newline at end of file diff --git a/docs/guides/implement-an-extension.html b/docs/guides/implement-an-extension.html index 57dc5de..4bd96d3 100644 --- a/docs/guides/implement-an-extension.html +++ b/docs/guides/implement-an-extension.html @@ -6,13 +6,13 @@ Implement an extension | Badger - +
- + \ No newline at end of file diff --git a/docs/intro.html b/docs/intro.html index 052d072..bb94598 100644 --- a/docs/intro.html +++ b/docs/intro.html @@ -6,13 +6,13 @@ Introduction | Badger - +

Introduction

Badger is an optimizer specifically designed for Accelerator Control Room (ACR). It's the spiritual successor of Ocelot optimizer.

Badger architecture

Badger abstracts an optimization run as an optimization algorithm interacts with an environment, by following some pre-defined rules. As visualized in the picture above, the environment is controlled by the algorithm and tunes/observes the control system/machine through an interface, while the users control/monitor the optimization flow through a graphical user interface (GUI) or a command line interface (CLI).

Algorithms, environments, and interfaces in Badger are all managed through a plugin system, and could be developed and maintained separately. The application interfaces (API) for creating the plugins are very straightforward and simple, yet abstractive enough to handle various situations.

Badger offers 3 modes to satisfy different user groups:

  • GUI mode, for ACR operators, enable them to perform regular optimization tasks with one click
  • CLI mode, for the command line lovers or the situation without a screen, configure and run the whole optimization in one line efficiently
  • API mode, for the algorithm developers, use the environments provided by Badger without the troubles to configure them

Important Concepts

As shown in the Badger schematic plot above, there are several terms/concepts in Badger, and their meaning are a little different with regard to their general definitions. Let's briefly go through the terms/concepts in Badger in the following sections.

Routine

An optimization setup in Badger is called a routine. A routine contains all the information needed to perform the optimization:

  • The optimization algorithm and its hyperparameters
  • The environment on which the optimization would be performed
  • The configuration of the optimization, such as variables, objectives, and constraints

To run an optimization in Badger, the users need to define the routine. Badger provides several ways to easily compose the routine, so no worries, you'll not have to write it by hands:)

Interface

An interface in Badger is a piece of code that talks to the underlying control system/machine. It communicates to the control system to:

  • Set a process variable (PVs) to some specific value
  • Get the value of a PV

An interface is also responsible to perform the configuration needed for communicating with the control system, and the configuration can be customized by passing a params dictionary to the interface.

The concept of interface was introduced to Badger for better code reuse. You don't have to copy-n-paste the same fundamental code again and again when coding your optimization problems for the same underlying control system. Now you could simply ask Badger to use the same interface, and focus more on the higher level logic of the problem.

tip

Interfaces are optional in Badger -- an interface is not needed if the optimization problem is simple enough (say, analytical function) that you can directly shape it into an environment.

Environment

An environment is Badger's way to (partially) abstract an optimization problem. A typical optimization problem usually consists of the variables to tune, and the objectives to optimize. A Badger environment defines all the interested variables and observations of a control system/machine. An optimization problem can be specified by stating which variables in the environment are the variables to tune, and which observations are the objectives to optimize. Furthermore, one can define the constraints for the optimization by picking up some observation from the environment and giving it a threshold.

Take the following case as an example. Assume that we have an accelerator control system and we'd like to tune the quadupoles QUAD:1, QUAD:2 and minimize the horizontal beam size on a screen BSIZE:X. We also want to keep the vertical beam size BSIZE:Y below a certain value. To do this in Badger, we could define an environment that has variables:

  • QUAD:1
  • QUAD:2

And observations:

  • BSIZE:X
  • BSIZE:Y

Then define a routine config to specify details of the optimization problem, as will be mentioned in the next section.

tip

One environment could support multiple relevant optimization problems -- just put all the variables and observations to the environment, and use routine config to select which variables/observations to use for the optimization.

Routine Config

A routine config is the counterpart of optimization problem abstraction with regard to environment. An optimization problem can be fully defined by an environment with a routine config.

On top of the variables and observations provided by environment, routine config tells Badger which and how variables/observations are used as the tuning variables/objectives/constraints.

Use the example from the last section, the routine config for the problem could be:

Routine Config
variables:
  - QUAD:1
  - QUAD:2
objectives:
  - BSIZE:X: MINIMIZE
constraints:
  - BSIZE:Y:
      - LESS_THAN
      - 0.5

The reasons to divide the optimization problem definition into two parts (environment and routine config) are:

  • Better code reuse
  • Operations in ACR usually require slightly changing a routine frequently, so it's good to have an abstraction for the frequently changed configurations (routine config), to avoid messing with the optimization source code

Features

One of Badger's core features is the ability to extend easily. Badger offers two ways to extend its capibility: making a plugin, or implementing an extension.

Plugin System

Algorithms, interfaces, and environments are all plugins in Badger. A plugin in Badger is a set of python scripts, a YAML config file, and an optional README.md. A typical file structure of a plugin looks like:

Plugin File Structure
|--<PLUGIN_ID>
    |--__init__.py
    |--configs.yaml
    |--README.md
    |--...

The role/feature of each file will be discussed in details later in the create a plugin section.

tip

One unique feature of Badger plugins is that plugins can be nested -- you can use any available plugins inside your own plugin. Say, one could combine two environments and create a new one effortlessly, thanks to this nestable nature of Badger plugins. You could explore the infinity possibilities by nesting plugins together with your imagination!

Extension System

Extension system is another way to extend Badger's capabilities, and in a sense it's more powerful than the plugin system, since it could make a batch of existing algorithms available in Badger in a few lines of code!

Let's assume that we already have an optimization platform/framework that provides a dozen of algorithms, and we'd like to use these algorithms to optimize on our machine environment. One way to do that is porting all these algorthms to Badger through the plugin system, and use Badger to perform the optimization. Extension system was designed just for this situation, since porting the algorithms one by one is tedious and inefficient. Extension system provides the APIs that are required to be implemented in order to "port" all the algorithms of another optimization framework/platform in one go. More details about extension system can be found in the implement an extension section.

With the extension system, Badger could use any existing algorithms from another optimization package. Currently, Badger has the following extensions available:

And more extensions are on the way (for example, teeport extension for remote optimization)!

- + \ No newline at end of file diff --git a/index.html b/index.html index 43ce2a2..d8fb747 100644 --- a/index.html +++ b/index.html @@ -6,13 +6,13 @@ Badger the Optimizer | Badger - +

Badger

The Missing Optimizer in ACR

Get Started

Easy to Use

Badger was specifically designed for operators. You could re-run an optimization routine with just one command/click.

Fast to Extend

Badger can be extended through its plugin system. Shape your algorithm/problem into a plugin in 5 minutes.

Multiple Mode

Badger can be used as a library, a command line tool, or a GUI application. Use Badger the way you want.

- + \ No newline at end of file