diff --git a/404.html b/404.html index a371c64..277080b 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/0e384e19.5cde9241.js b/assets/js/0e384e19.58ce0a6e.js similarity index 96% rename from assets/js/0e384e19.5cde9241.js rename to assets/js/0e384e19.58ce0a6e.js index f21d4b1..bf5c654 100644 --- a/assets/js/0e384e19.5cde9241.js +++ b/assets/js/0e384e19.58ce0a6e.js @@ -1 +1 @@ -"use strict";(self.webpackChunkbadger_home=self.webpackChunkbadger_home||[]).push([[671],{9881:function(e,t,n){n.r(t),n.d(t,{frontMatter:function(){return s},contentTitle:function(){return l},metadata:function(){return m},toc:function(){return p},default:function(){return c}});var i=n(7462),a=n(3366),o=(n(7294),n(3905)),r=["components"],s={sidebar_position:1},l="Introduction",m={unversionedId:"intro",id:"intro",isDocsHomePage:!1,title:"Introduction",description:"Badger is an optimizer specifically designed for Accelerator Control Room (ACR). It's the spiritual successor of Ocelot optimizer.",source:"@site/docs/intro.md",sourceDirName:".",slug:"/intro",permalink:"/Badger/docs/intro",editUrl:"https://github.com/SLAC-ML/Badger-Home/edit/master/docs/intro.md",tags:[],version:"current",sidebarPosition:1,frontMatter:{sidebar_position:1},sidebar:"tutorialSidebar",next:{title:"Installation",permalink:"/Badger/docs/getting-started/installation"}},p=[{value:"Important Concepts",id:"important-concepts",children:[{value:"Routine",id:"routine",children:[],level:3},{value:"Interface",id:"interface",children:[],level:3},{value:"Environment",id:"environment",children:[],level:3},{value:"Routine Config",id:"routine-config",children:[],level:3}],level:2},{value:"Features",id:"features",children:[{value:"Plugin System",id:"plugin-system",children:[],level:3},{value:"Extension System",id:"extension-system",children:[],level:3}],level:2}],d={toc:p};function c(e){var t=e.components,s=(0,a.Z)(e,r);return(0,o.kt)("wrapper",(0,i.Z)({},d,s,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("h1",{id:"introduction"},"Introduction"),(0,o.kt)("p",null,"Badger is an optimizer specifically designed for Accelerator Control Room (ACR). It's the spiritual successor of ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/ocelot-collab/optimizer"},"Ocelot optimizer"),"."),(0,o.kt)("p",null,(0,o.kt)("img",{alt:"Badger architecture",src:n(4879).Z})),(0,o.kt)("p",null,"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)."),(0,o.kt)("p",null,"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."),(0,o.kt)("p",null,"Badger offers 3 modes to satisfy different user groups:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},"GUI mode, for ACR operators, enable them to perform regular optimization tasks with one click"),(0,o.kt)("li",{parentName:"ul"},"CLI mode, for the command line lovers or the situation without a screen, configure and run the whole optimization in one line efficiently"),(0,o.kt)("li",{parentName:"ul"},"API mode, for the algorithm developers, use the environments provided by Badger without the troubles to configure them")),(0,o.kt)("h2",{id:"important-concepts"},"Important Concepts"),(0,o.kt)("p",null,"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."),(0,o.kt)("h3",{id:"routine"},"Routine"),(0,o.kt)("p",null,"An optimization setup in Badger is called a routine. A routine contains all the information needed to perform the optimization:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},"The optimization algorithm and its hyperparameters"),(0,o.kt)("li",{parentName:"ul"},"The environment on which the optimization would be performed"),(0,o.kt)("li",{parentName:"ul"},"The configuration of the optimization, such as variables, objectives, and constraints")),(0,o.kt)("p",null,"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:)"),(0,o.kt)("h3",{id:"interface"},"Interface"),(0,o.kt)("p",null,"An interface in Badger is a piece of code that talks to the underlying control system/machine. It communicates to the control system to:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},"Set a process variable (PVs) to some specific value"),(0,o.kt)("li",{parentName:"ul"},"Get the value of a PV")),(0,o.kt)("p",null,"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 ",(0,o.kt)("inlineCode",{parentName:"p"},"params")," dictionary to the interface."),(0,o.kt)("p",null,"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."),(0,o.kt)("div",{className:"admonition admonition-tip alert alert--success"},(0,o.kt)("div",{parentName:"div",className:"admonition-heading"},(0,o.kt)("h5",{parentName:"div"},(0,o.kt)("span",{parentName:"h5",className:"admonition-icon"},(0,o.kt)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"12",height:"16",viewBox:"0 0 12 16"},(0,o.kt)("path",{parentName:"svg",fillRule:"evenodd",d:"M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"}))),"tip")),(0,o.kt)("div",{parentName:"div",className:"admonition-content"},(0,o.kt)("p",{parentName:"div"},"Interfaces are ",(0,o.kt)("strong",{parentName:"p"},"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."))),(0,o.kt)("h3",{id:"environment"},"Environment"),(0,o.kt)("p",null,"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 ",(0,o.kt)("strong",{parentName:"p"},"variables")," and ",(0,o.kt)("strong",{parentName:"p"},"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."),(0,o.kt)("p",null,"Take the following case as an example. Assume that we have an accelerator control system and we'd like to tune the quadupoles ",(0,o.kt)("inlineCode",{parentName:"p"},"QUAD:1"),", ",(0,o.kt)("inlineCode",{parentName:"p"},"QUAD:2")," and minimize the horizontal beam size on a screen ",(0,o.kt)("inlineCode",{parentName:"p"},"BSIZE:X"),". We also want to keep the vertical beam size ",(0,o.kt)("inlineCode",{parentName:"p"},"BSIZE:Y")," below a certain value. To do this in Badger, we could define an environment that has variables:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("inlineCode",{parentName:"li"},"QUAD:1")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("inlineCode",{parentName:"li"},"QUAD:2"))),(0,o.kt)("p",null,"And observations:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("inlineCode",{parentName:"li"},"BSIZE:X")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("inlineCode",{parentName:"li"},"BSIZE:Y"))),(0,o.kt)("p",null,"Then define a ",(0,o.kt)("strong",{parentName:"p"},(0,o.kt)("a",{parentName:"strong",href:"#routine-config"},"routine config"))," to specify details of the optimization problem, as will be mentioned in the next section."),(0,o.kt)("div",{className:"admonition admonition-tip alert alert--success"},(0,o.kt)("div",{parentName:"div",className:"admonition-heading"},(0,o.kt)("h5",{parentName:"div"},(0,o.kt)("span",{parentName:"h5",className:"admonition-icon"},(0,o.kt)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"12",height:"16",viewBox:"0 0 12 16"},(0,o.kt)("path",{parentName:"svg",fillRule:"evenodd",d:"M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"}))),"tip")),(0,o.kt)("div",{parentName:"div",className:"admonition-content"},(0,o.kt)("p",{parentName:"div"},"One environment could support multiple ",(0,o.kt)("strong",{parentName:"p"},"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."))),(0,o.kt)("h3",{id:"routine-config"},"Routine Config"),(0,o.kt)("p",null,"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."),(0,o.kt)("p",null,"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."),(0,o.kt)("p",null,"Use the example from the last section, the routine config for the problem could be:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Routine Config"',title:'"Routine','Config"':!0},"variables:\n - QUAD:1\n - QUAD:2\nobjectives:\n - BSIZE:X: MINIMIZE\nconstraints:\n - BSIZE:Y:\n - LESS_THAN\n - 0.5\n")),(0,o.kt)("p",null,"The reasons to divide the optimization problem definition into two parts (environment and routine config) are:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},"Better code reuse"),(0,o.kt)("li",{parentName:"ul"},"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")),(0,o.kt)("h2",{id:"features"},"Features"),(0,o.kt)("p",null,"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."),(0,o.kt)("h3",{id:"plugin-system"},"Plugin System"),(0,o.kt)("p",null,"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:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Plugin File Structure"',title:'"Plugin',File:!0,'Structure"':!0},"|--\n |--__init__.py\n |--configs.yaml\n |--README.md\n |--...\n")),(0,o.kt)("p",null,"The role/feature of each file will be discussed in details later in the ",(0,o.kt)("a",{parentName:"p",href:"guides/create-a-plugin"},"create a plugin")," section."),(0,o.kt)("div",{className:"admonition admonition-tip alert alert--success"},(0,o.kt)("div",{parentName:"div",className:"admonition-heading"},(0,o.kt)("h5",{parentName:"div"},(0,o.kt)("span",{parentName:"h5",className:"admonition-icon"},(0,o.kt)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"12",height:"16",viewBox:"0 0 12 16"},(0,o.kt)("path",{parentName:"svg",fillRule:"evenodd",d:"M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"}))),"tip")),(0,o.kt)("div",{parentName:"div",className:"admonition-content"},(0,o.kt)("p",{parentName:"div"},"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!"))),(0,o.kt)("h3",{id:"extension-system"},"Extension System"),(0,o.kt)("p",null,"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!"),(0,o.kt)("p",null,"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 ",(0,o.kt)("a",{parentName:"p",href:"guides/implement-an-extension"},"implement an extension")," section."),(0,o.kt)("p",null,"With the extension system, Badger could use any existing algorithms from another optimization package. Currently, Badger has the following extensions available:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://github.com/ChristopherMayes/Xopt"},"xopt"))),(0,o.kt)("p",null,"And more extensions are on the way (for example, ",(0,o.kt)("a",{parentName:"p",href:"https://teeport.ml/intro"},"teeport")," extension for remote optimization)!"))}c.isMDXComponent=!0},4879:function(e,t,n){t.Z=n.p+"assets/images/architecture-b0910240b36cb72a945230d415864f3a.png"}}]); \ No newline at end of file +"use strict";(self.webpackChunkbadger_home=self.webpackChunkbadger_home||[]).push([[671],{9881:function(e,t,n){n.r(t),n.d(t,{frontMatter:function(){return s},contentTitle:function(){return l},metadata:function(){return m},toc:function(){return p},default:function(){return c}});var i=n(7462),a=n(3366),o=(n(7294),n(3905)),r=["components"],s={sidebar_position:1},l="Introduction",m={unversionedId:"intro",id:"intro",isDocsHomePage:!1,title:"Introduction",description:"Badger is an optimizer specifically designed for Accelerator Control Room (ACR). It's the spiritual successor of Ocelot optimizer.",source:"@site/docs/intro.md",sourceDirName:".",slug:"/intro",permalink:"/Badger/docs/intro",editUrl:"https://github.com/SLAC-ML/Badger-Home/edit/master/docs/intro.md",tags:[],version:"current",sidebarPosition:1,frontMatter:{sidebar_position:1},sidebar:"tutorialSidebar",next:{title:"Installation",permalink:"/Badger/docs/getting-started/installation"}},p=[{value:"Important concepts",id:"important-concepts",children:[{value:"Routine",id:"routine",children:[],level:3},{value:"Interface",id:"interface",children:[],level:3},{value:"Environment",id:"environment",children:[],level:3},{value:"Routine config",id:"routine-config",children:[],level:3}],level:2},{value:"Features",id:"features",children:[{value:"Plugin system",id:"plugin-system",children:[],level:3},{value:"Extension system",id:"extension-system",children:[],level:3}],level:2}],d={toc:p};function c(e){var t=e.components,s=(0,a.Z)(e,r);return(0,o.kt)("wrapper",(0,i.Z)({},d,s,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("h1",{id:"introduction"},"Introduction"),(0,o.kt)("p",null,"Badger is an optimizer specifically designed for Accelerator Control Room (ACR). It's the spiritual successor of ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/ocelot-collab/optimizer"},"Ocelot optimizer"),"."),(0,o.kt)("p",null,(0,o.kt)("img",{alt:"Badger architecture",src:n(4879).Z})),(0,o.kt)("p",null,"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)."),(0,o.kt)("p",null,"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."),(0,o.kt)("p",null,"Badger offers 3 modes to satisfy different user groups:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},"GUI mode, for ACR operators, enable them to perform regular optimization tasks with one click"),(0,o.kt)("li",{parentName:"ul"},"CLI mode, for the command line lovers or the situation without a screen, configure and run the whole optimization in one line efficiently"),(0,o.kt)("li",{parentName:"ul"},"API mode, for the algorithm developers, use the environments provided by Badger without the troubles to configure them")),(0,o.kt)("h2",{id:"important-concepts"},"Important concepts"),(0,o.kt)("p",null,"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."),(0,o.kt)("h3",{id:"routine"},"Routine"),(0,o.kt)("p",null,"An optimization setup in Badger is called a routine. A routine contains all the information needed to perform the optimization:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},"The optimization algorithm and its hyperparameters"),(0,o.kt)("li",{parentName:"ul"},"The environment on which the optimization would be performed"),(0,o.kt)("li",{parentName:"ul"},"The configuration of the optimization, such as variables, objectives, and constraints")),(0,o.kt)("p",null,"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:)"),(0,o.kt)("h3",{id:"interface"},"Interface"),(0,o.kt)("p",null,"An interface in Badger is a piece of code that talks to the underlying control system/machine. It communicates to the control system to:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},"Set a process variable (PVs) to some specific value"),(0,o.kt)("li",{parentName:"ul"},"Get the value of a PV")),(0,o.kt)("p",null,"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 ",(0,o.kt)("inlineCode",{parentName:"p"},"params")," dictionary to the interface."),(0,o.kt)("p",null,"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."),(0,o.kt)("div",{className:"admonition admonition-tip alert alert--success"},(0,o.kt)("div",{parentName:"div",className:"admonition-heading"},(0,o.kt)("h5",{parentName:"div"},(0,o.kt)("span",{parentName:"h5",className:"admonition-icon"},(0,o.kt)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"12",height:"16",viewBox:"0 0 12 16"},(0,o.kt)("path",{parentName:"svg",fillRule:"evenodd",d:"M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"}))),"tip")),(0,o.kt)("div",{parentName:"div",className:"admonition-content"},(0,o.kt)("p",{parentName:"div"},"Interfaces are ",(0,o.kt)("strong",{parentName:"p"},"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."))),(0,o.kt)("h3",{id:"environment"},"Environment"),(0,o.kt)("p",null,"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 ",(0,o.kt)("strong",{parentName:"p"},"variables")," and ",(0,o.kt)("strong",{parentName:"p"},"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."),(0,o.kt)("p",null,"Take the following case as an example. Assume that we have an accelerator control system and we'd like to tune the quadupoles ",(0,o.kt)("inlineCode",{parentName:"p"},"QUAD:1"),", ",(0,o.kt)("inlineCode",{parentName:"p"},"QUAD:2")," and minimize the horizontal beam size on a screen ",(0,o.kt)("inlineCode",{parentName:"p"},"BSIZE:X"),". We also want to keep the vertical beam size ",(0,o.kt)("inlineCode",{parentName:"p"},"BSIZE:Y")," below a certain value. To do this in Badger, we could define an environment that has variables:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("inlineCode",{parentName:"li"},"QUAD:1")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("inlineCode",{parentName:"li"},"QUAD:2"))),(0,o.kt)("p",null,"And observations:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("inlineCode",{parentName:"li"},"BSIZE:X")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("inlineCode",{parentName:"li"},"BSIZE:Y"))),(0,o.kt)("p",null,"Then define a ",(0,o.kt)("strong",{parentName:"p"},(0,o.kt)("a",{parentName:"strong",href:"#routine-config"},"routine config"))," to specify details of the optimization problem, as will be mentioned in the next section."),(0,o.kt)("div",{className:"admonition admonition-tip alert alert--success"},(0,o.kt)("div",{parentName:"div",className:"admonition-heading"},(0,o.kt)("h5",{parentName:"div"},(0,o.kt)("span",{parentName:"h5",className:"admonition-icon"},(0,o.kt)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"12",height:"16",viewBox:"0 0 12 16"},(0,o.kt)("path",{parentName:"svg",fillRule:"evenodd",d:"M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"}))),"tip")),(0,o.kt)("div",{parentName:"div",className:"admonition-content"},(0,o.kt)("p",{parentName:"div"},"One environment could support multiple ",(0,o.kt)("strong",{parentName:"p"},"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."))),(0,o.kt)("h3",{id:"routine-config"},"Routine config"),(0,o.kt)("p",null,"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."),(0,o.kt)("p",null,"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."),(0,o.kt)("p",null,"Use the example from the last section, the routine config for the problem could be:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Routine Config"',title:'"Routine','Config"':!0},"variables:\n - QUAD:1\n - QUAD:2\nobjectives:\n - BSIZE:X: MINIMIZE\nconstraints:\n - BSIZE:Y:\n - LESS_THAN\n - 0.5\n")),(0,o.kt)("p",null,"The reasons to divide the optimization problem definition into two parts (environment and routine config) are:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},"Better code reuse"),(0,o.kt)("li",{parentName:"ul"},"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")),(0,o.kt)("h2",{id:"features"},"Features"),(0,o.kt)("p",null,"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."),(0,o.kt)("h3",{id:"plugin-system"},"Plugin system"),(0,o.kt)("p",null,"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:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Plugin File Structure"',title:'"Plugin',File:!0,'Structure"':!0},"|--\n |--__init__.py\n |--configs.yaml\n |--README.md\n |--...\n")),(0,o.kt)("p",null,"The role/feature of each file will be discussed in details later in the ",(0,o.kt)("a",{parentName:"p",href:"guides/create-a-plugin"},"create a plugin")," section."),(0,o.kt)("div",{className:"admonition admonition-tip alert alert--success"},(0,o.kt)("div",{parentName:"div",className:"admonition-heading"},(0,o.kt)("h5",{parentName:"div"},(0,o.kt)("span",{parentName:"h5",className:"admonition-icon"},(0,o.kt)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"12",height:"16",viewBox:"0 0 12 16"},(0,o.kt)("path",{parentName:"svg",fillRule:"evenodd",d:"M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"}))),"tip")),(0,o.kt)("div",{parentName:"div",className:"admonition-content"},(0,o.kt)("p",{parentName:"div"},"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!"))),(0,o.kt)("h3",{id:"extension-system"},"Extension system"),(0,o.kt)("p",null,"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!"),(0,o.kt)("p",null,"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 ",(0,o.kt)("a",{parentName:"p",href:"guides/implement-an-extension"},"implement an extension")," section."),(0,o.kt)("p",null,"With the extension system, Badger could use any existing algorithms from another optimization package. Currently, Badger has the following extensions available:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://github.com/ChristopherMayes/Xopt"},"xopt"))),(0,o.kt)("p",null,"And more extensions are on the way (for example, ",(0,o.kt)("a",{parentName:"p",href:"https://teeport.ml/intro"},"teeport")," extension for remote optimization)!"))}c.isMDXComponent=!0},4879:function(e,t,n){t.Z=n.p+"assets/images/architecture-b0910240b36cb72a945230d415864f3a.png"}}]); \ No newline at end of file diff --git a/assets/js/6eada910.5341980a.js b/assets/js/6eada910.5341980a.js deleted file mode 100644 index e78e831..0000000 --- a/assets/js/6eada910.5341980a.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkbadger_home=self.webpackChunkbadger_home||[]).push([[769],{377:function(e,n,t){t.r(n),t.d(n,{frontMatter:function(){return l},contentTitle:function(){return s},metadata:function(){return u},toc:function(){return d},default:function(){return p}});var a=t(7462),i=t(3366),o=(t(7294),t(3905)),r=["components"],l={sidebar_position:2},s="Tutorial",u={unversionedId:"getting-started/tutorial",id:"getting-started/tutorial",isDocsHomePage:!1,title:"Tutorial",description:"Make sure you have Badger installed and setup.",source:"@site/docs/getting-started/tutorial.md",sourceDirName:"getting-started",slug:"/getting-started/tutorial",permalink:"/Badger/docs/getting-started/tutorial",editUrl:"https://github.com/SLAC-ML/Badger-Home/edit/master/docs/getting-started/tutorial.md",tags:[],version:"current",sidebarPosition:2,frontMatter:{sidebar_position:2},sidebar:"tutorialSidebar",previous:{title:"Installation",permalink:"/Badger/docs/getting-started/installation"},next:{title:"API Usage",permalink:"/Badger/docs/guides/api-usage"}},d=[{value:"Get basic information about Badger",id:"get-basic-information-about-badger",children:[],level:2},{value:"Run and save an optimization",id:"run-and-save-an-optimization",children:[],level:2},{value:"Re-run an optimization",id:"re-run-an-optimization",children:[],level:2},{value:"View the historical optimization data",id:"view-the-historical-optimization-data",children:[],level:2},{value:"Create a simple environment",id:"create-a-simple-environment",children:[],level:2}],m={toc:d};function p(e){var n=e.components,t=(0,i.Z)(e,r);return(0,o.kt)("wrapper",(0,a.Z)({},m,t,{components:n,mdxType:"MDXLayout"}),(0,o.kt)("h1",{id:"tutorial"},"Tutorial"),(0,o.kt)("div",{className:"admonition admonition-note alert alert--secondary"},(0,o.kt)("div",{parentName:"div",className:"admonition-heading"},(0,o.kt)("h5",{parentName:"div"},(0,o.kt)("span",{parentName:"h5",className:"admonition-icon"},(0,o.kt)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,o.kt)("path",{parentName:"svg",fillRule:"evenodd",d:"M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"}))),"Heads-up")),(0,o.kt)("div",{parentName:"div",className:"admonition-content"},(0,o.kt)("p",{parentName:"div"},"Make sure you have Badger ",(0,o.kt)("a",{parentName:"p",href:"./installation"},"installed and setup"),"."))),(0,o.kt)("p",null,"Let's discover ",(0,o.kt)("strong",{parentName:"p"},"Badger in less than 5 minutes"),". All of the following commands are assumed to be run in a terminal (Mac, Windows, and Linux are supported)."),(0,o.kt)("h2",{id:"get-basic-information-about-badger"},"Get basic information about Badger"),(0,o.kt)("p",null,"First let's verify that Badger has been installed and configured correctly:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-shell"},"badger\n")),(0,o.kt)("p",null,"Which should give you something like:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="output"',title:'"output"'},"name: Badger the optimizer\nversion: 0.5.3\nplugin root: /root/badger/plugins\ndatabase root: /root/badger/db\nlogbook root: /root/badger/logbook\narchive root: /root/badger/archived\nextensions:\n - xopt\n")),(0,o.kt)("h2",{id:"run-and-save-an-optimization"},"Run and save an optimization"),(0,o.kt)("p",null,"Create a yaml file under your ",(0,o.kt)("inlineCode",{parentName:"p"},"pwd")," (where you would run an optimization with Badger) with the following content:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"variables:\n - x2\nobjectives:\n - c1\n")),(0,o.kt)("p",null,"To run and save an optimization, run:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-shell"},"badger run -a silly -e TNK -c config.yaml -s helloworld\n")),(0,o.kt)("p",null,"Badger will ask you to review the optimization routine:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="output"',title:'"output"'},"Please review the routine to be run:\n\n=== Optimization Routine ===\nname: mottled-sloth\nalgo: silly\nenv: TNK\nalgo_params:\n dimension: 1\n max_iter: 42\nenv_params: null\nconfig:\n variables:\n - x2: 0 -> 3.14159\n objectives:\n - c1: MINIMIZE\n constraints: null\n\nProceed ([y]/n)?\n")),(0,o.kt)("p",null,"Hit return to confirm. Badger will print out a table of all the evaluated\nsolutions along the run:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-shell",metastring:'{3,19} title="output"',"{3,19}":!0,title:'"output"'},"| iter | c1 | x2 |\n----------------------------------------\n| 1 | -1.094 | 0.07432 |\n| 2 | 3.563 | 2.159 |\n| 3 | 8.749 | 3.138 |\n| 4 | 5.351 | 2.54 |\n| 5 | 8.17 | 3.045 |\n| 6 | 6.536 | 2.763 |\n| 7 | 3.007 | 2.027 |\n| 8 | -1.089 | 0.1063 |\n| 9 | 4.127 | 2.286 |\n| 10 | 3.519 | 2.149 |\n| 11 | 6.647 | 2.783 |\n| 12 | 1.074 | 1.474 |\n| 13 | -0.8621 | 0.4878 |\n| 14 | 3.821 | 2.218 |\n| 15 | -0.9228 | 0.421 |\n| 16 | 6.205 | 2.703 |\n| 17 | -1.1 | 0.005409 |\n| 18 | 8.224 | 3.054 |\n| 19 | 7.584 | 2.947 |\n| 20 | -0.8961 | 0.4515 |\n| 21 | -1.093 | 0.08082 |\n| 22 | 1.293 | 1.547 |\n| 23 | 2.593 | 1.922 |\n| 24 | 5.563 | 2.581 |\n| 25 | 2.046 | 1.774 |\n| 26 | 2.501 | 1.898 |\n| 27 | -0.8853 | 0.4633 |\n| 28 | -0.5459 | 0.7444 |\n| 29 | -0.8881 | 0.4604 |\n| 30 | -0.4806 | 0.787 |\n| 31 | -1.1 | 0.01909 |\n| 32 | 0.4855 | 1.259 |\n| 33 | 0.8217 | 1.386 |\n| 34 | 6.036 | 2.671 |\n| 35 | -0.7649 | 0.5789 |\n| 36 | 0.06972 | 1.082 |\n| 37 | 7.325 | 2.903 |\n| 38 | -0.7764 | 0.5689 |\n| 39 | 6.042 | 2.673 |\n| 40 | 5.008 | 2.471 |\n| 41 | 4.274 | 2.318 |\n| 42 | -0.8561 | 0.4939 |\n========================================\n")),(0,o.kt)("p",null,"You would notice that the optimal solutions (in this case\noptimal means minimal ",(0,o.kt)("inlineCode",{parentName:"p"},"c1"),") at the evaluation time are highlighted."),(0,o.kt)("p",null,"In the example above, we use the ",(0,o.kt)("strong",{parentName:"p"},"silly")," algorithm (which is just a random search algorithm) to optimize the ",(0,o.kt)("strong",{parentName:"p"},"TNK"),"\nenvironment, as shown in the reviewed routine. Environment ",(0,o.kt)("strong",{parentName:"p"},"TNK")," has 2\nvariables and 5 observations:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-yaml",metastring:'{7,8,10-14} title="TNK environment"',"{7,8,10-14}":!0,title:'"TNK','environment"':!0},"name: TNK\nversion: '0.1'\ndependencies:\n - numpy\nparams: null\nvariables:\n - x1: 0 -> 3.14159\n - x2: 0 -> 3.14159\nobservations:\n - y1\n - y2\n - c1\n - c2\n - some_array\n")),(0,o.kt)("p",null,"We specify in the ",(0,o.kt)("inlineCode",{parentName:"p"},"config.yaml")," that we would like to tune varaible ",(0,o.kt)("inlineCode",{parentName:"p"},"x2"),", and minimize observation ",(0,o.kt)("inlineCode",{parentName:"p"},"c1")," of environment ",(0,o.kt)("strong",{parentName:"p"},"TNK")," as objective. The configuration that could reproduce the whole optimization setup is called a ",(0,o.kt)("strong",{parentName:"p"},"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)."),(0,o.kt)("p",null,"We just saved the routine of the run as ",(0,o.kt)("inlineCode",{parentName:"p"},"helloworld"),". Now you could view the routine again by:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-shell"},"badger routine helloworld\n")),(0,o.kt)("h2",{id:"re-run-an-optimization"},"Re-run an optimization"),(0,o.kt)("p",null,"We can re-run a saved routine in Badger. Let's re-run the ",(0,o.kt)("inlineCode",{parentName:"p"},"helloworld")," routine that we just saved:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-shell"},"badger routine helloworld -r\n")),(0,o.kt)("p",null,"Badger would behave exactly the same way as the first time you run the routine."),(0,o.kt)("h2",{id:"view-the-historical-optimization-data"},"View the historical optimization data"),(0,o.kt)("p",null,"You can ",(0,o.kt)("inlineCode",{parentName:"p"},"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:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-shell",metastring:'{4} title="Badger archive root file structure"',"{4}":!0,title:'"Badger',archive:!0,root:!0,file:!0,'structure"':!0},"|--2021\n |--2021-11\n |--2021-11-24\n |--BadgerOpt-2021-11-24-133007.yaml\n |--BadgerOpt-2021-11-24-113241.yaml\n |--...\n |--...\n |--...\n|--...\n")),(0,o.kt)("p",null,"The yaml data file contains the routine information and the solutions evaluated during the run. The content would look like this:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-yaml",metastring:'title="BadgerOpt-2021-11-24-133007.yaml"',title:'"BadgerOpt-2021-11-24-133007.yaml"'},"routine:\n name: helloworld\n algo: silly\n env: TNK\n algo_params:\n dimension: 1\n max_iter: 10\n env_params: null\n config:\n variables:\n - x2:\n - 0.0\n - 3.1416\n objectives:\n - c1: MINIMIZE\n constraints: null\ndata:\n timestamp:\n - 24-Nov-2021 13:30:06\n - 24-Nov-2021 13:30:06\n - 24-Nov-2021 13:30:06\n - 24-Nov-2021 13:30:06\n - 24-Nov-2021 13:30:06\n - 24-Nov-2021 13:30:06\n - 24-Nov-2021 13:30:06\n - 24-Nov-2021 13:30:07\n - 24-Nov-2021 13:30:07\n - 24-Nov-2021 13:30:07\n c1:\n - 2.093905436806936\n - 2.6185501712620036\n - -0.8170601778601619\n - 7.869183841178197\n - -1.0945113202011\n - 0.514833333947652\n - -1.0331173238615994\n - 1.4523371516674013\n - 1.3610274948700156\n - -0.0042273815683477045\n x2:\n - 1.78715008793524\n - 1.9283542649788197\n - 0.5319208795862764\n - 2.9948595695254556\n - 0.07408562477903413\n - 1.2707609271407632\n - 0.2586168520000207\n - 1.5976035652399507\n - 1.5687662333407153\n - 1.0467915830917118\n")),(0,o.kt)("h2",{id:"create-a-simple-environment"},"Create a simple environment"),(0,o.kt)("p",null,"Now let's create a simple Badger environment and run optimization on it."))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/6eada910.fb2223d7.js b/assets/js/6eada910.fb2223d7.js new file mode 100644 index 0000000..7b4fe13 --- /dev/null +++ b/assets/js/6eada910.fb2223d7.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkbadger_home=self.webpackChunkbadger_home||[]).push([[769],{377:function(e,n,t){t.r(n),t.d(n,{frontMatter:function(){return l},contentTitle:function(){return s},metadata:function(){return u},toc:function(){return d},default:function(){return p}});var a=t(7462),i=t(3366),o=(t(7294),t(3905)),r=["components"],l={sidebar_position:2},s="Tutorial",u={unversionedId:"getting-started/tutorial",id:"getting-started/tutorial",isDocsHomePage:!1,title:"Tutorial",description:"Make sure you have Badger installed and setup.",source:"@site/docs/getting-started/tutorial.md",sourceDirName:"getting-started",slug:"/getting-started/tutorial",permalink:"/Badger/docs/getting-started/tutorial",editUrl:"https://github.com/SLAC-ML/Badger-Home/edit/master/docs/getting-started/tutorial.md",tags:[],version:"current",sidebarPosition:2,frontMatter:{sidebar_position:2},sidebar:"tutorialSidebar",previous:{title:"Installation",permalink:"/Badger/docs/getting-started/installation"},next:{title:"API Usage",permalink:"/Badger/docs/guides/api-usage"}},d=[{value:"Get basic information about Badger",id:"get-basic-information-about-badger",children:[],level:2},{value:"Run and save an optimization",id:"run-and-save-an-optimization",children:[],level:2},{value:"Rerun an optimization",id:"rerun-an-optimization",children:[],level:2},{value:"View the historical optimization data",id:"view-the-historical-optimization-data",children:[],level:2},{value:"Create a simple environment",id:"create-a-simple-environment",children:[],level:2}],m={toc:d};function p(e){var n=e.components,t=(0,i.Z)(e,r);return(0,o.kt)("wrapper",(0,a.Z)({},m,t,{components:n,mdxType:"MDXLayout"}),(0,o.kt)("h1",{id:"tutorial"},"Tutorial"),(0,o.kt)("div",{className:"admonition admonition-note alert alert--secondary"},(0,o.kt)("div",{parentName:"div",className:"admonition-heading"},(0,o.kt)("h5",{parentName:"div"},(0,o.kt)("span",{parentName:"h5",className:"admonition-icon"},(0,o.kt)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,o.kt)("path",{parentName:"svg",fillRule:"evenodd",d:"M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"}))),"Heads-up")),(0,o.kt)("div",{parentName:"div",className:"admonition-content"},(0,o.kt)("p",{parentName:"div"},"Make sure you have Badger ",(0,o.kt)("a",{parentName:"p",href:"./installation"},"installed and setup"),"."))),(0,o.kt)("p",null,"Let's discover ",(0,o.kt)("strong",{parentName:"p"},"Badger in less than 5 minutes"),". All of the following commands are assumed to be run in a terminal (Mac, Windows, and Linux are supported)."),(0,o.kt)("h2",{id:"get-basic-information-about-badger"},"Get basic information about Badger"),(0,o.kt)("p",null,"First let's verify that Badger has been installed and configured correctly:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-shell"},"badger\n")),(0,o.kt)("p",null,"Which should give you something like:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="output"',title:'"output"'},"name: Badger the optimizer\nversion: 0.5.3\nplugin root: /root/badger/plugins\ndatabase root: /root/badger/db\nlogbook root: /root/badger/logbook\narchive root: /root/badger/archived\nextensions:\n - xopt\n")),(0,o.kt)("h2",{id:"run-and-save-an-optimization"},"Run and save an optimization"),(0,o.kt)("p",null,"Create a yaml file under your ",(0,o.kt)("inlineCode",{parentName:"p"},"pwd")," (where you would run an optimization with Badger) with the following content:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-yaml",metastring:'title="config.yaml"',title:'"config.yaml"'},"variables:\n - x2\nobjectives:\n - c1\n")),(0,o.kt)("p",null,"To run and save an optimization, run:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-shell"},"badger run -a silly -e TNK -c config.yaml -s helloworld\n")),(0,o.kt)("p",null,"Badger will ask you to review the optimization routine:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="output"',title:'"output"'},"Please review the routine to be run:\n\n=== Optimization Routine ===\nname: mottled-sloth\nalgo: silly\nenv: TNK\nalgo_params:\n dimension: 1\n max_iter: 42\nenv_params: null\nconfig:\n variables:\n - x2: 0 -> 3.14159\n objectives:\n - c1: MINIMIZE\n constraints: null\n\nProceed ([y]/n)?\n")),(0,o.kt)("p",null,"Hit return to confirm. Badger will print out a table of all the evaluated\nsolutions along the run:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-shell",metastring:'{3,19} title="output"',"{3,19}":!0,title:'"output"'},"| iter | c1 | x2 |\n----------------------------------------\n| 1 | -1.094 | 0.07432 |\n| 2 | 3.563 | 2.159 |\n| 3 | 8.749 | 3.138 |\n| 4 | 5.351 | 2.54 |\n| 5 | 8.17 | 3.045 |\n| 6 | 6.536 | 2.763 |\n| 7 | 3.007 | 2.027 |\n| 8 | -1.089 | 0.1063 |\n| 9 | 4.127 | 2.286 |\n| 10 | 3.519 | 2.149 |\n| 11 | 6.647 | 2.783 |\n| 12 | 1.074 | 1.474 |\n| 13 | -0.8621 | 0.4878 |\n| 14 | 3.821 | 2.218 |\n| 15 | -0.9228 | 0.421 |\n| 16 | 6.205 | 2.703 |\n| 17 | -1.1 | 0.005409 |\n| 18 | 8.224 | 3.054 |\n| 19 | 7.584 | 2.947 |\n| 20 | -0.8961 | 0.4515 |\n| 21 | -1.093 | 0.08082 |\n| 22 | 1.293 | 1.547 |\n| 23 | 2.593 | 1.922 |\n| 24 | 5.563 | 2.581 |\n| 25 | 2.046 | 1.774 |\n| 26 | 2.501 | 1.898 |\n| 27 | -0.8853 | 0.4633 |\n| 28 | -0.5459 | 0.7444 |\n| 29 | -0.8881 | 0.4604 |\n| 30 | -0.4806 | 0.787 |\n| 31 | -1.1 | 0.01909 |\n| 32 | 0.4855 | 1.259 |\n| 33 | 0.8217 | 1.386 |\n| 34 | 6.036 | 2.671 |\n| 35 | -0.7649 | 0.5789 |\n| 36 | 0.06972 | 1.082 |\n| 37 | 7.325 | 2.903 |\n| 38 | -0.7764 | 0.5689 |\n| 39 | 6.042 | 2.673 |\n| 40 | 5.008 | 2.471 |\n| 41 | 4.274 | 2.318 |\n| 42 | -0.8561 | 0.4939 |\n========================================\n")),(0,o.kt)("p",null,"You would notice that the optimal solutions (in this case\noptimal means minimal ",(0,o.kt)("inlineCode",{parentName:"p"},"c1"),") at the evaluation time are highlighted."),(0,o.kt)("p",null,"In the example above, we use the ",(0,o.kt)("strong",{parentName:"p"},"silly")," algorithm (which is just a random search algorithm) to optimize the ",(0,o.kt)("strong",{parentName:"p"},"TNK"),"\nenvironment, as shown in the reviewed routine. Environment ",(0,o.kt)("strong",{parentName:"p"},"TNK")," has 2\nvariables and 5 observations:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-yaml",metastring:'{7,8,10-14} title="TNK environment"',"{7,8,10-14}":!0,title:'"TNK','environment"':!0},"name: TNK\nversion: '0.1'\ndependencies:\n - numpy\nparams: null\nvariables:\n - x1: 0 -> 3.14159\n - x2: 0 -> 3.14159\nobservations:\n - y1\n - y2\n - c1\n - c2\n - some_array\n")),(0,o.kt)("p",null,"We specify in the ",(0,o.kt)("inlineCode",{parentName:"p"},"config.yaml")," that we would like to tune varaible ",(0,o.kt)("inlineCode",{parentName:"p"},"x2"),", and minimize observation ",(0,o.kt)("inlineCode",{parentName:"p"},"c1")," of environment ",(0,o.kt)("strong",{parentName:"p"},"TNK")," as objective. The configuration that could reproduce the whole optimization setup is called a ",(0,o.kt)("strong",{parentName:"p"},"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)."),(0,o.kt)("p",null,"We just saved the routine of the run as ",(0,o.kt)("inlineCode",{parentName:"p"},"helloworld"),". Now you could view the routine again by:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-shell"},"badger routine helloworld\n")),(0,o.kt)("h2",{id:"rerun-an-optimization"},"Rerun an optimization"),(0,o.kt)("p",null,"We can rerun a saved routine in Badger. Let's rerun the ",(0,o.kt)("inlineCode",{parentName:"p"},"helloworld")," routine that we just saved:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-shell"},"badger routine helloworld -r\n")),(0,o.kt)("p",null,"Badger would behave exactly the same way as the first time you run the routine."),(0,o.kt)("h2",{id:"view-the-historical-optimization-data"},"View the historical optimization data"),(0,o.kt)("p",null,"You can ",(0,o.kt)("inlineCode",{parentName:"p"},"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:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-shell",metastring:'{4} title="Badger archive root file structure"',"{4}":!0,title:'"Badger',archive:!0,root:!0,file:!0,'structure"':!0},"|--2021\n |--2021-11\n |--2021-11-24\n |--BadgerOpt-2021-11-24-133007.yaml\n |--BadgerOpt-2021-11-24-113241.yaml\n |--...\n |--...\n |--...\n|--...\n")),(0,o.kt)("p",null,"The yaml data file contains the routine information and the solutions evaluated during the run. The content would look like this:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-yaml",metastring:'title="BadgerOpt-2021-11-24-133007.yaml"',title:'"BadgerOpt-2021-11-24-133007.yaml"'},"routine:\n name: helloworld\n algo: silly\n env: TNK\n algo_params:\n dimension: 1\n max_iter: 10\n env_params: null\n config:\n variables:\n - x2:\n - 0.0\n - 3.1416\n objectives:\n - c1: MINIMIZE\n constraints: null\ndata:\n timestamp:\n - 24-Nov-2021 13:30:06\n - 24-Nov-2021 13:30:06\n - 24-Nov-2021 13:30:06\n - 24-Nov-2021 13:30:06\n - 24-Nov-2021 13:30:06\n - 24-Nov-2021 13:30:06\n - 24-Nov-2021 13:30:06\n - 24-Nov-2021 13:30:07\n - 24-Nov-2021 13:30:07\n - 24-Nov-2021 13:30:07\n c1:\n - 2.093905436806936\n - 2.6185501712620036\n - -0.8170601778601619\n - 7.869183841178197\n - -1.0945113202011\n - 0.514833333947652\n - -1.0331173238615994\n - 1.4523371516674013\n - 1.3610274948700156\n - -0.0042273815683477045\n x2:\n - 1.78715008793524\n - 1.9283542649788197\n - 0.5319208795862764\n - 2.9948595695254556\n - 0.07408562477903413\n - 1.2707609271407632\n - 0.2586168520000207\n - 1.5976035652399507\n - 1.5687662333407153\n - 1.0467915830917118\n")),(0,o.kt)("h2",{id:"create-a-simple-environment"},"Create a simple environment"),(0,o.kt)("p",null,"Now let's create a simple Badger environment and run optimization on it."),(0,o.kt)("p",null,(0,o.kt)("strong",{parentName:"p"},"WIP")))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/e689722c.95133075.js b/assets/js/e689722c.95133075.js new file mode 100644 index 0000000..ae85719 --- /dev/null +++ b/assets/js/e689722c.95133075.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkbadger_home=self.webpackChunkbadger_home||[]).push([[276],{3075:function(e,n,t){t.r(n),t.d(n,{frontMatter:function(){return s},contentTitle:function(){return l},metadata:function(){return p},toc:function(){return u},default:function(){return g}});var a=t(7462),i=t(3366),r=(t(7294),t(3905)),o=["components"],s={sidebar_position:1},l="API Usage",p={unversionedId:"guides/api-usage",id:"guides/api-usage",isDocsHomePage:!1,title:"API Usage",description:"Badger can be imported as a regular python package, and you could use the plugins/utils that Badger offers in your own python script.",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"}},u=[{value:"Use an algorithm",id:"use-an-algorithm",children:[],level:2},{value:"Use an interface",id:"use-an-interface",children:[],level:2},{value:"Use an environment",id:"use-an-environment",children:[],level:2}],d={toc:u};function g(e){var n=e.components,t=(0,i.Z)(e,o);return(0,r.kt)("wrapper",(0,a.Z)({},d,t,{components:n,mdxType:"MDXLayout"}),(0,r.kt)("h1",{id:"api-usage"},"API Usage"),(0,r.kt)("p",null,"Badger can be imported as a regular python package, and you could use the plugins/utils that Badger offers in your own python script."),(0,r.kt)("div",{className:"admonition admonition-note alert alert--secondary"},(0,r.kt)("div",{parentName:"div",className:"admonition-heading"},(0,r.kt)("h5",{parentName:"div"},(0,r.kt)("span",{parentName:"h5",className:"admonition-icon"},(0,r.kt)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,r.kt)("path",{parentName:"svg",fillRule:"evenodd",d:"M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"}))),"Heads-up")),(0,r.kt)("div",{parentName:"div",className:"admonition-content"},(0,r.kt)("p",{parentName:"div"},"Make sure you have Badger ",(0,r.kt)("a",{parentName:"p",href:"../getting-started/installation"},"installed and setup"),"."))),(0,r.kt)("h2",{id:"use-an-algorithm"},"Use an algorithm"),(0,r.kt)("p",null,"Badger has a ",(0,r.kt)("inlineCode",{parentName:"p"},"get_algo")," API to get a specific algorithm."),(0,r.kt)("p",null,"The following code gets an algorithm named ",(0,r.kt)("inlineCode",{parentName:"p"},"silly")," (which is a random search algorithm) from Badger."),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-python"},"import numpy as np\nfrom badger.factory import get_algo\n\n# Define a test evaluate function\ndef evaluate(X):\n Y = np.linalg.norm(X, axis=1).reshape(-1, 1) # objectives\n I = None # inequality constraints\n E = None # equality constraints\n\n # Show the progress\n print(Y)\n\n return Y, I, E\n\n# Get the silly algorithm from Badger\noptimize, configs = get_algo('silly')\n\n# Optimize the test evaluate function\noptimize(evaluate, configs['params'])\n")),(0,r.kt)("h2",{id:"use-an-interface"},"Use an interface"),(0,r.kt)("p",null,"Badger has a ",(0,r.kt)("inlineCode",{parentName:"p"},"get_intf")," API to get a specific interface."),(0,r.kt)("p",null,"The following code gets an interface named ",(0,r.kt)("inlineCode",{parentName:"p"},"silly")," and constructs an instance of the interface."),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-python"},"from badger.factory import get_intf\n\n# Get the silly interface from Badger\nInterface, configs = get_intf('silly')\nintf = Interface(configs['params'])\n\n# Test get/set channels\nintf.get_value('c1')\n# Output: 0\n\nintf.set_value('c1', 1.0)\nintf.get_value('c1')\n# Output: 1.0\n")),(0,r.kt)("h2",{id:"use-an-environment"},"Use an environment"),(0,r.kt)("p",null,"Badger has a ",(0,r.kt)("inlineCode",{parentName:"p"},"get_env")," API to get a specific environment."),(0,r.kt)("p",null,"The following code gets and instantiates an environment named ",(0,r.kt)("inlineCode",{parentName:"p"},"silly")," from Badger. Note that it uses the ",(0,r.kt)("inlineCode",{parentName:"p"},"silly")," interface instance ",(0,r.kt)("inlineCode",{parentName:"p"},"intf")," from the ",(0,r.kt)("a",{parentName:"p",href:"#use-an-interface"},"last")," section."),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-python"},"from badger.factory import get_env\n\n# Get the silly environment from Badger\nEnvironment, configs = get_env('silly')\nenv = Environment(intf, configs['params'])\n\n# Investigate the silly env\nenv.list_vars()\n# Output: ['q1', 'q2', 'q3', 'q4']\n\nenv.list_obses()\n# Output: ['l1', 'l2']\n\nenv.get_var('q1') # q1 in env maps to c1 in intf\n# Output: 1.0\n\nenv.get_obs('l2') # l2 norm of (q1, q2, q3, q4)\n# Output: 1.0\n\nenv.set_var('q2', 1)\nenv.get_obs('l2')\n# Output: 1.4142135623730951\n")),(0,r.kt)("p",null,"Now we can define an evaluate function based on the ",(0,r.kt)("inlineCode",{parentName:"p"},"silly")," env, and use the ",(0,r.kt)("inlineCode",{parentName:"p"},"silly")," algorithm from the ",(0,r.kt)("a",{parentName:"p",href:"#use-an-algorithm"},"use an algorithm")," section to optimize it."),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-python"},"# Define an evaluate function based on the env\ndef evaluate(X):\n # Note that X is a 2D array\n Y = []\n for x in X:\n env.set_vars(['q1', 'q2', 'q3', 'q4'][:len(x)], x)\n y = env.get_obs('l2')\n Y.append(y)\n Y = np.array(Y).reshape(-1, 1)\n I = None\n E = None\n\n # Show the progress\n print(Y)\n\n return Y, I, E\n\n# Optimize the evaluate function with silly algorithm\noptimize(evaluate, {'dimension': 4, 'max_iter': 42})\n")))}g.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/e689722c.babc55c6.js b/assets/js/e689722c.babc55c6.js deleted file mode 100644 index 2c6a6a6..0000000 --- a/assets/js/e689722c.babc55c6.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:"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/runtime~main.2c5deef4.js b/assets/js/runtime~main.8605b11c.js similarity index 94% rename from assets/js/runtime~main.2c5deef4.js rename to assets/js/runtime~main.8605b11c.js index 132da56..7b3874c 100644 --- a/assets/js/runtime~main.2c5deef4.js +++ b/assets/js/runtime~main.8605b11c.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:"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=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:"95133075",288:"5c11f824",489:"a7bdca31",514:"84f0b0c2",535:"4b1b2a12",592:"914f4003",608:"6ce78891",610:"73be0d48",618:"1d60fd4f",653:"69cb3bb8",659:"5669b728",671:"58ce0a6e",707:"5cb9c152",769:"fb2223d7",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 cb66501..30e56ad 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 206f163..a4cca1f 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 893bd9a..e5e63b8 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 0a11d20..a4b16eb 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 01df757..a232c11 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 6545c87..e26afe8 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 c5d0dd7..ff7f3e5 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 675357d..a40c59c 100644 --- a/docs/getting-started/tutorial.html +++ b/docs/getting-started/tutorial.html @@ -6,7 +6,7 @@ Tutorial | Badger - + @@ -15,8 +15,8 @@ solutions along the run:

output
|    iter    |     c1     |     x2     |
----------------------------------------
|  1         | -1.094     |  0.07432   |
|  2         |  3.563     |  2.159     |
|  3         |  8.749     |  3.138     |
|  4         |  5.351     |  2.54      |
|  5         |  8.17      |  3.045     |
|  6         |  6.536     |  2.763     |
|  7         |  3.007     |  2.027     |
|  8         | -1.089     |  0.1063    |
|  9         |  4.127     |  2.286     |
|  10        |  3.519     |  2.149     |
|  11        |  6.647     |  2.783     |
|  12        |  1.074     |  1.474     |
|  13        | -0.8621    |  0.4878    |
|  14        |  3.821     |  2.218     |
|  15        | -0.9228    |  0.421     |
|  16        |  6.205     |  2.703     |
|  17        | -1.1       |  0.005409  |
|  18        |  8.224     |  3.054     |
|  19        |  7.584     |  2.947     |
|  20        | -0.8961    |  0.4515    |
|  21        | -1.093     |  0.08082   |
|  22        |  1.293     |  1.547     |
|  23        |  2.593     |  1.922     |
|  24        |  5.563     |  2.581     |
|  25        |  2.046     |  1.774     |
|  26        |  2.501     |  1.898     |
|  27        | -0.8853    |  0.4633    |
|  28        | -0.5459    |  0.7444    |
|  29        | -0.8881    |  0.4604    |
|  30        | -0.4806    |  0.787     |
|  31        | -1.1       |  0.01909   |
|  32        |  0.4855    |  1.259     |
|  33        |  0.8217    |  1.386     |
|  34        |  6.036     |  2.671     |
|  35        | -0.7649    |  0.5789    |
|  36        |  0.06972   |  1.082     |
|  37        |  7.325     |  2.903     |
|  38        | -0.7764    |  0.5689    |
|  39        |  6.042     |  2.673     |
|  40        |  5.008     |  2.471     |
|  41        |  4.274     |  2.318     |
|  42        | -0.8561    |  0.4939    |
========================================

You would notice that the optimal solutions (in this case 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.

- +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

Rerun an optimization

We can rerun a saved routine in Badger. Let's rerun 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.

WIP

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

API Usage

Badger can be imported as a regular python package, and you could use the plugins/utils that Badger offers in your own python script.

Heads-up

Make sure you have Badger installed and setup.

Use an algorithm

Badger has a get_algo API to get a specific algorithm.

The following code gets an algorithm named silly (which is a random search algorithm) from Badger.

import numpy as np
from badger.factory import get_algo

# Define a test evaluate function
def evaluate(X):
    Y = np.linalg.norm(X, axis=1).reshape(-1, 1)  # objectives
    I = None  # inequality constraints
    E = None  # equality constraints

    # Show the progress
    print(Y)

    return Y, I, E

# Get the silly algorithm from Badger
optimize, configs = get_algo('silly')

# Optimize the test evaluate function
optimize(evaluate, configs['params'])

Use an interface

Badger has a get_intf API to get a specific interface.

The following code gets an interface named silly and constructs an instance of the interface.

from badger.factory import get_intf

# Get the silly interface from Badger
Interface, configs = get_intf('silly')
intf = Interface(configs['params'])

# Test get/set channels
intf.get_value('c1')
# Output: 0

intf.set_value('c1', 1.0)
intf.get_value('c1')
# Output: 1.0

Use an environment

Badger has a get_env API to get a specific environment.

The following code gets and instantiates an environment named silly from Badger. Note that it uses the silly interface instance intf from the last section.

from badger.factory import get_env

# Get the silly environment from Badger
Environment, configs = get_env('silly')
env = Environment(intf, configs['params'])

# Investigate the silly env
env.list_vars()
# Output: ['q1', 'q2', 'q3', 'q4']

env.list_obses()
# Output: ['l1', 'l2']

env.get_var('q1')  # q1 in env maps to c1 in intf
# Output: 1.0

env.get_obs('l2')  # l2 norm of (q1, q2, q3, q4)
# Output: 1.0

env.set_var('q2', 1)
env.get_obs('l2')
# Output: 1.4142135623730951

Now we can define an evaluate function based on the silly env, and use the silly algorithm from the use an algorithm section to optimize it.

# Define an evaluate function based on the env
def evaluate(X):
    # Note that X is a 2D array
    Y = []
    for x in X:
        env.set_vars(['q1', 'q2', 'q3', 'q4'][:len(x)], x)
        y = env.get_obs('l2')
        Y.append(y)
    Y = np.array(Y).reshape(-1, 1)
    I = None
    E = None

    # Show the progress
    print(Y)

    return Y, I, E

# Optimize the evaluate function with silly algorithm
optimize(evaluate, {'dimension': 4, 'max_iter': 42})
+ \ No newline at end of file diff --git a/docs/guides/cli-usage.html b/docs/guides/cli-usage.html index e57f3e0..bb338da 100644 --- a/docs/guides/cli-usage.html +++ b/docs/guides/cli-usage.html @@ -6,13 +6,13 @@ 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 546d633..8ff170d 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 b558ed0..7d0a233 100644 --- a/docs/guides/gui-usage.html +++ b/docs/guides/gui-usage.html @@ -6,13 +6,13 @@ 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 4bd96d3..c9d79e0 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 bb94598..185bc8d 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)!

- +

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 d8fb747..c1da788 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