From aa7820f50481e0c5703ff3c6f6e370c27992a13c Mon Sep 17 00:00:00 2001 From: "Sara A. Miskovich" Date: Mon, 31 Mar 2025 10:51:22 -0700 Subject: [PATCH 1/4] add docs files and updated workflows --- README.md | 4 +- docs/algorithms.md | 76 ++ docs/api/evaluator.md | 1 + docs/api/generators.md | 1 + docs/api/generators/bayesian.md | 18 + docs/api/generators/genetic.md | 1 + docs/api/generators/scipy.md | 3 + docs/api/vocs.md | 1 + docs/api/xopt.md | 1 + docs/assets/Xopt-logo.png | Bin 0 -> 85101 bytes docs/assets/xopt_overview.pdf | Bin 0 -> 777786 bytes .../basic/checkpointing_and_restarts.ipynb | 180 ++++ docs/examples/basic/dump.yml | 229 +++++ docs/examples/basic/xopt_basic.ipynb | 636 ++++++++++++ docs/examples/basic/xopt_evaluator.ipynb | 576 +++++++++++ docs/examples/basic/xopt_generator.ipynb | 285 ++++++ docs/examples/basic/xopt_parallel.ipynb | 596 +++++++++++ docs/examples/basic/xopt_vocs.ipynb | 662 ++++++++++++ .../bayes_exp/bayesian_exploration.ipynb | 315 ++++++ .../bayesian_exploration_from_yaml.ipynb | 208 ++++ ...bayesian_exploration_w_interpolation.ipynb | 353 +++++++ .../bayesian_exploration_with_nans.ipynb | 232 +++++ docs/examples/ga/cnsga_tnk.ipynb | 688 +++++++++++++ docs/examples/ga/nsga2.ipynb | 374 +++++++ .../gp_model_creation/model_creation.ipynb | 259 +++++ .../multi_objective_bayes_opt/mggpo.ipynb | 308 ++++++ .../multi_objective_bayes_opt/mobo.ipynb | 232 +++++ .../mobo_from_yaml.ipynb | 243 +++++ .../multi_fidelity_mobo.ipynb | 430 ++++++++ docs/examples/scipy/latin_hypercube.ipynb | 191 ++++ .../sequential/extremum_seeking.ipynb | 952 ++++++++++++++++++ docs/examples/sequential/neldermead.ipynb | 827 +++++++++++++++ docs/examples/sequential/rcds.ipynb | 835 +++++++++++++++ .../bax_tutorial.ipynb | 430 ++++++++ .../benchmarking.ipynb | 329 ++++++ .../bo_tutorial.ipynb | 360 +++++++ .../constrained_bo_tutorial.ipynb | 279 +++++ .../custom_model.ipynb | 327 ++++++ .../custom_objective.ipynb | 278 +++++ .../fixed_features.ipynb | 361 +++++++ .../hessian_kernel.ipynb | 174 ++++ .../heteroskedastic_noise_tutorial.ipynb | 362 +++++++ .../interpolate_tutorial.ipynb | 340 +++++++ .../multi_fidelity_simple.ipynb | 405 ++++++++ .../noisy_bo_tutorial.ipynb | 360 +++++++ .../time_dependent_bo.ipynb | 421 ++++++++ .../turbo_tutorial.ipynb | 424 ++++++++ .../upper_confidence_bound.ipynb | 194 ++++ docs/index.md | 188 ++++ docs/installation.md | 58 ++ docs/overrides/main.html | 11 + docs/stylesheets/extra.css | 31 + mkdocs.yml | 151 +++ 53 files changed, 15199 insertions(+), 1 deletion(-) create mode 100644 docs/algorithms.md create mode 100644 docs/api/evaluator.md create mode 100644 docs/api/generators.md create mode 100644 docs/api/generators/bayesian.md create mode 100644 docs/api/generators/genetic.md create mode 100644 docs/api/generators/scipy.md create mode 100644 docs/api/vocs.md create mode 100644 docs/api/xopt.md create mode 100644 docs/assets/Xopt-logo.png create mode 100644 docs/assets/xopt_overview.pdf create mode 100644 docs/examples/basic/checkpointing_and_restarts.ipynb create mode 100644 docs/examples/basic/dump.yml create mode 100644 docs/examples/basic/xopt_basic.ipynb create mode 100644 docs/examples/basic/xopt_evaluator.ipynb create mode 100644 docs/examples/basic/xopt_generator.ipynb create mode 100644 docs/examples/basic/xopt_parallel.ipynb create mode 100644 docs/examples/basic/xopt_vocs.ipynb create mode 100644 docs/examples/bayes_exp/bayesian_exploration.ipynb create mode 100644 docs/examples/bayes_exp/bayesian_exploration_from_yaml.ipynb create mode 100644 docs/examples/bayes_exp/bayesian_exploration_w_interpolation.ipynb create mode 100644 docs/examples/bayes_exp/bayesian_exploration_with_nans.ipynb create mode 100644 docs/examples/ga/cnsga_tnk.ipynb create mode 100644 docs/examples/ga/nsga2.ipynb create mode 100644 docs/examples/gp_model_creation/model_creation.ipynb create mode 100644 docs/examples/multi_objective_bayes_opt/mggpo.ipynb create mode 100644 docs/examples/multi_objective_bayes_opt/mobo.ipynb create mode 100644 docs/examples/multi_objective_bayes_opt/mobo_from_yaml.ipynb create mode 100644 docs/examples/multi_objective_bayes_opt/multi_fidelity_mobo.ipynb create mode 100644 docs/examples/scipy/latin_hypercube.ipynb create mode 100644 docs/examples/sequential/extremum_seeking.ipynb create mode 100644 docs/examples/sequential/neldermead.ipynb create mode 100644 docs/examples/sequential/rcds.ipynb create mode 100644 docs/examples/single_objective_bayes_opt/bax_tutorial.ipynb create mode 100644 docs/examples/single_objective_bayes_opt/benchmarking.ipynb create mode 100644 docs/examples/single_objective_bayes_opt/bo_tutorial.ipynb create mode 100644 docs/examples/single_objective_bayes_opt/constrained_bo_tutorial.ipynb create mode 100644 docs/examples/single_objective_bayes_opt/custom_model.ipynb create mode 100644 docs/examples/single_objective_bayes_opt/custom_objective.ipynb create mode 100644 docs/examples/single_objective_bayes_opt/fixed_features.ipynb create mode 100644 docs/examples/single_objective_bayes_opt/hessian_kernel.ipynb create mode 100644 docs/examples/single_objective_bayes_opt/heteroskedastic_noise_tutorial.ipynb create mode 100644 docs/examples/single_objective_bayes_opt/interpolate_tutorial.ipynb create mode 100644 docs/examples/single_objective_bayes_opt/multi_fidelity_simple.ipynb create mode 100644 docs/examples/single_objective_bayes_opt/noisy_bo_tutorial.ipynb create mode 100644 docs/examples/single_objective_bayes_opt/time_dependent_bo.ipynb create mode 100644 docs/examples/single_objective_bayes_opt/turbo_tutorial.ipynb create mode 100644 docs/examples/single_objective_bayes_opt/upper_confidence_bound.ipynb create mode 100644 docs/index.md create mode 100644 docs/installation.md create mode 100644 docs/overrides/main.html create mode 100644 docs/stylesheets/extra.css create mode 100644 mkdocs.yml diff --git a/README.md b/README.md index bff8613..3671f1f 100644 --- a/README.md +++ b/README.md @@ -1 +1,3 @@ -# Xopt-docs +# Xopt Docs + +New repository for Xopt documentation. Under development. diff --git a/docs/algorithms.md b/docs/algorithms.md new file mode 100644 index 0000000..5f1e1d8 --- /dev/null +++ b/docs/algorithms.md @@ -0,0 +1,76 @@ +Pre-Configured Generators in Xopt +=============== +A number of algorithms are implemented in Xopt using the ```Generator``` class for +off-the-shelf usage. +Below is a +description of the different generators that are available in Xopt and their target +use cases. + +RandomGenerator +=============== +Generates random points in the input space according to ```VOCS```. + +Bayesian Generators +== +All of the generators here use Bayesian optimization (BO) type methods to solve single +objective, multi objective and characterization problems. Bayesian generators +incorperate unknown constrianing functions into optimization based on what is +specified in ```VOCS``` + +- ```ExpectedImprovementGenerator```: implements Expected Improvement single + objective BO. Automatically balances trade-offs between exploration and + exploitation and is thus useful for general purpose optimization. +- ```UpperConfidenceBoundGenerator```: implements Upper Confidence Bound single + objective BO. Requires a hyperparameter ```beta``` that explicitly sets the tradeoff + between exploration and exploitation. Default value of ```beta=2``` is a good + starting point. Increase $\beta$ to prioritize exploration and decrease ```beta``` to + prioritize exploitation. +- ```BayesianExplorationGenerator```: implements the Bayesian Exploration algorithm + for function characterization. This algorithm selects observation points that + maximize model uncertainty, thus picking points that maximize the information gain + about the target function at each iteration. If the target function is found to be + more sensative to one parameter this generator will adjust sampling frequency to + adapt. Note: specifying ```vocs.objective[1]``` + to ```MAXIMIZE``` or ```MINIMIZE``` does not change the behavior of this generator. +- ```MOBOGenerator```: implements Multi-Objective BO using the + Expected Hypervolume Improvement (EHVI) acquisition function. This is an ideal + general purpose multi-objective optimizer when objective evaluations cannot be + massively parallelized (< 10 parallel evaluations). +- ```MGGPOGenerator```: implements Multi-Generation Gaussian Process Optimization using + the + Expected Hypervolume Improvement (EHVI) acquisition function. This is an ideal + general purpose multi-objective optimizer when objective evaluations can be + massively parallelized (> 10 parallel evaluations) . +- ```MultiFidelityGenerator```: implements Multi-Fidelity BO which can take + advantage of lower fidelity evaluations of objectives and constraints to reduce + the computational cost of solving single or multi-objective optimization problems + in sequential or small scale parallel (< 10 parallel evaluations) + contexts. + +Evolutionary Generators +===== +- ```CNSGAGenerator```: implements Continuous Non-dominated Sorted Genetic Algorithm + which as a good general purpose evolutionary algorithm used for solving + multi-objective optimization problems where evaluating the objective is relatively + cheap and massively parallelizable (above 5-10 parallel evaluations). + +Extremum Seeking Generators +=== +- ```ExtremumSeekingGenerator```: implements the Extremum Seeking algorithm which is + ideal for solving optimization problems that are suceptable to drifts. + +Scipy Generators +=== +These generators serve as wrappers for algorithms implemented in scipy. +- ```NelderMeadGenerator```: implements Nelder-Mead (simplex) optimization. + +RCDS Generators +=== +- ```RCDSGenerator```: implements the RCDS algorithm. RCDS could be applied in noisy + online optimization scenarios + +Custom Generators +==== +Any general algorithm can be implemented by subclassing the abstract ```Generator``` +class and used in the Xopt framework. If you implement a generator for your use case +please consider opening a pull request so that we can add it to Xopt! diff --git a/docs/api/evaluator.md b/docs/api/evaluator.md new file mode 100644 index 0000000..75bf269 --- /dev/null +++ b/docs/api/evaluator.md @@ -0,0 +1 @@ +::: xopt.evaluator.Evaluator diff --git a/docs/api/generators.md b/docs/api/generators.md new file mode 100644 index 0000000..d1e108a --- /dev/null +++ b/docs/api/generators.md @@ -0,0 +1 @@ +::: xopt.generator diff --git a/docs/api/generators/bayesian.md b/docs/api/generators/bayesian.md new file mode 100644 index 0000000..c2c3b59 --- /dev/null +++ b/docs/api/generators/bayesian.md @@ -0,0 +1,18 @@ +::: xopt.generators.bayesian.bayesian_generator.BayesianGenerator +::: xopt.generators.bayesian.bayesian_exploration.BayesianExplorationGenerator +::: xopt.generators.bayesian.expected_improvement.ExpectedImprovementGenerator +::: xopt.generators.bayesian.expected_improvement.TDExpectedImprovementGenerator +::: xopt.generators.bayesian.mobo.MOBOGenerator +::: xopt.generators.bayesian.upper_confidence_bound.UpperConfidenceBoundGenerator +::: xopt.generators.bayesian.upper_confidence_bound.TDUpperConfidenceBoundGenerator +::: xopt.generators.bayesian.multi_fidelity.MultiFidelityGenerator +::: xopt.generators.bayesian.turbo.TurboController +- get_trust_region +- update_trust_region +- get_data_in_trust_region +- update_state +- reset +::: xopt.generators.bayesian.turbo.OptimizeTurboController +- minimize +::: xopt.generators.bayesian.turbo.SafetyTurboController +::: xopt.generators.bayesian.turbo.EntropyTurboController diff --git a/docs/api/generators/genetic.md b/docs/api/generators/genetic.md new file mode 100644 index 0000000..baeeb9d --- /dev/null +++ b/docs/api/generators/genetic.md @@ -0,0 +1 @@ +::: xopt.generators.ga.cnsga.CNSGAGenerator diff --git a/docs/api/generators/scipy.md b/docs/api/generators/scipy.md new file mode 100644 index 0000000..7bbf3c0 --- /dev/null +++ b/docs/api/generators/scipy.md @@ -0,0 +1,3 @@ +::: xopt.generators.sequential.neldermead.NelderMeadGenerator +::: xopt.generators.sequential.rcds.RCDSGenerator +::: xopt.generators.sequential.extremumseeking.ExtremumSeekingGenerator diff --git a/docs/api/vocs.md b/docs/api/vocs.md new file mode 100644 index 0000000..bc03d4d --- /dev/null +++ b/docs/api/vocs.md @@ -0,0 +1 @@ +::: xopt.vocs.VOCS diff --git a/docs/api/xopt.md b/docs/api/xopt.md new file mode 100644 index 0000000..c389fa2 --- /dev/null +++ b/docs/api/xopt.md @@ -0,0 +1 @@ +::: xopt.Xopt diff --git a/docs/assets/Xopt-logo.png b/docs/assets/Xopt-logo.png new file mode 100644 index 0000000000000000000000000000000000000000..ec2b2cf61068144ac8e4f9cfba4475b25cdc3224 GIT binary patch literal 85101 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%0ADH0YhAd8DodvC1y0XHdGm;zK@!%d@mV zR!c&yf*-k$nq{x}q`JzR&x>N38Z!bP6IG-VI10W3n%>Cf*Onm|gmLPGN^>BxtXOz8 zd2yoZy^Dm@R#ZF(y5?PC24mlZ`9C-7rPApVGt({OcHAU~a4S@|G2JL%G|}~-3!<21tDytKqZO@*AjD)e1un(oi+bPv1RTbQ~!=~@$nGo zE38m0LmQI!Bb97MX-(AWJS0(SHfGVaa8j4yt$!xmTL*o?5vujttM9O8^P{M(gPD)? zw^ep6fSc->cRlFgQ2gI|$C9(+*0b-Eg z|Ly69N13g{A{inVVr$~r3!DnwG&No4e9{0W>(wXwC1+pm`p9)^-;zCSCamf0np1j> zmV+GO1ayR&exp}ZVcbKOX*$}E!>08HtTFQP(mV>3UJR@>*DTx6wOsVM=oq;w>&m0FzD}zGrSkJsETORFsWOQm0|0Nxb7{jywH#GlMT?%xUIM7|Z&$dpg zKI)Yk`7?QDRsFOcC9ldYz(_IOP`qhgn1u7be&8*HC#$tn7wc#NU0VUHa9;;p>Uux* z6W`4+{a~*h-7}x}0`)8b>e;H1t@_`p?0oe0kWF6G;y1jJo%X8bQK!q4PZ>Z@zJB;E z`INokQTKG4|55$3%B#1%S*G#yBdC&Ga^sn9MA7TKwC#5Um)dv%3%Oerx80`!`4jlk-+N=AY#jsjTF!Xy6~i~Ij_?>=|kk^u-jUHx3vIVCg!0D;!C9smFU literal 0 HcmV?d00001 diff --git a/docs/assets/xopt_overview.pdf b/docs/assets/xopt_overview.pdf new file mode 100644 index 0000000000000000000000000000000000000000..27996c3c9016da1713b0380f32e1bdb2edf812d3 GIT binary patch literal 777786 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

+t1Y9Br2a!#45!^HIix0i?kS{qOnT7JkHrzt#J@ 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 bxr?XArXbtuS|4pjUx zREV}@{-C=GJ@2XtPe}V`EL`Y8mMMN~aA=SV|E$DNE^qNq!e369W2Nh&J=$eJd=R>MbZQxAIq{_e!3i}PU)s^LCWtHSUJSx7f&P|UG2En(@ z>vS~Lm9WG0UuHgl5;?hc|LDCTKK$WyhG#1|W8xOTUs;I3dgpWx1^?k8IQ6f^yaJT^ zQyjjjQ!KQT7|{6s{rvpZ=Qv!Yl%50F^f(eGf2f6n1`<@IMe5J(o!&+B$5}M4i?~r` z0BtAGb|0VmLyoy>x}-e7Uzx-coS68}$RzwRYr=-enwaBQbxFkBUo`LNXQ&<*+=c%y z+s-{ODutC_QdQU3+}_^S(gffyD=982D!xWLbQA~SI1SVO4c1_xWr-)q{t^5o$e(fI z^(c9GoGB~iSK#ANcK0p}Ue_kZDmxikK z4F|!0bZq4O&`GX)TwDmqUqf5UBom5mi0Fq!5MBTDB%Q4eWBb(l7?3K z@$k?P1^>JZxSyFZCi^4!&+Kl{>?kDBd8fY<;6IEe{{bwe0Ja6*_U6WvjGF9Z2Qf^q z%hP@)kL&}?_qohBP{~e-48-P%YqgiFP&`nKf%u-JP8!=a=t<#RxpWSyvz-kUAV-4r@3`iPqUBG~xKyT>LjQ4u3;(lV z$k^Ucfqs}FUUud{EnmS?)SkS?f`yAESCW-dKA>71skJQu!QXNUX=q;H&(OR?f8Kwu zSz$iLAQ(DV1rMQqDYADDh)m4LEv>9?YH4o+^jDPRW@n^=%6$T}O+?T8qvuL;m}t7Q zH`@Wz9mT=<>+oMBOOqx3>pX)0(ZikfrMamw{xpIIA}_sI@4DbqA8*3&A38lWfT;?_ ztmFt^SL;1nH|VZZQ&yNV#fmQvv(-!_H$VJ_Pd%@U;KOyaf5>LW`h$TASg*sekLaT? zG_JsDPyENp9t!^FaXq3Hb6f-5_wU8Z7Rrh;f*lSR{(9sY_H}&jNvULICIovsnD4-= z^!&kp)j1J8Q=Rk7^MP2{E`;EVuFl>ev8g#ll{F1bXxH0RS5sM>%Sua%i;hGQmrU$M z;>K6?d6@QZu?y<)>Pk=0^A0KYa+=$GgBw!1J8J>{bb22mE{)*t{j4`Xf&7JOmwfxsv3`L6#dB~`*iEw%BYa)Z0t<&W)08bR{CAT__X1e@a#ga@5&Z4I zkqRYcR7LwQe4{@bGMDKyp9hzg&cg_VVu6p)H1>aC4&K2rDD^3;YCx$^dvilgMKPPj zOpFc>4MY(Zd02$R!TnQcUl!?)k_O|AYjKN+Qz& z;Opb%?duoB5@q`MSw$Z38y%=Z6xN%40{C0g+~ub$Jlgwv|uz%;nO0fHY;56zHg|NFc<@JyTY9vg ztF0L%jcQ7QoVmFQng&cNZtR}x+Y@48me44^jdAb{j7rYPFRj6Bht|g0ilUsfr05`T z4`)YPTU!TbcfS-`$6*xjR( z!1a#hRWxwn-+#QftBta%2OjliJ)LF1UYeX@VO5gUA)hS%@EqRwV)LxF+EO+%Cdhri z`3|mv{^Qy|84C=BFZlb3mIFslQ1Bn(I&!7O1;M$`7JTj_Cn=kITJH^;M;L ztmNnrZ+FN2)|TcL*0u=$@6kWU#DCh*oEPrvYGn#bJ`jcf8totJ6~xor~C^ud@OE2YUhjeMb)+Xs#|~C58FA*zDN~v!jYY<0gjxdZHB1#CII777v$F z4@(pDKdhd~DF7OlFyCkVokj%z{y~60+V~#nYN;y9!s-)yjG(oDiK2|~MKK+fEJ=pp zk7a^tN^;;_3yZ|f6Z{tji^%(LMbCem{WH&Kza)6(IeyL6$vY%EC9|l!rm+Q~zooIJ zJfFpk4e@ugw>95uYP#FZ(#F}HMc=6~G5%Z`n;9MG$))|P{#ChWyoIA<6;He|t!D|P z7k>i&?o%zKZnb9?Aow5Z?d$9BJKodH)3>s>FoAO)=+BzcK#$>XNG$%1e+KBkj9F#v zjiAL7>g|9oqK{n<9!G#;FbstG

  • dwssxqKZW2w42}cP-jf~|1{eK*;=Vh+t@7&s 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

    DzrJJ1qsw>+`)_`u6AYxYgy**V6069= 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 eE#=8pH4vij!5w&6%?i&ChjEiNHKtGGqY< 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

    p$;1)vN-(j|q zUFPgrm)e^X{0)DASCCo-j#c+UA|5HJTAvcf|6oh)`(n4(>7&=>aI@R}cw8>0xIRRT zE1h1qT@g&Ee=&Z^hDokc6aS?}TSO!a;#(fA9Rl6C&atUT-MllV&89xcxy{(=RYaBy zpIqP~6k!$4<`CBeD8k#kLbPD)^&VeOWX@>r?a04tbXvj6gs1@(f>bNn83jnJ>$bcF znPcE6M$R13=;}O9{cOP|$(IJacbq6P=C^1yYB9c`B4P-fwrTc(>d-|xeYd`0O}E$# zW2sli5e|jz-qqPG6e+WhEd%!^X$Os)d5^0;6ev=#h zxB1uZ`@@uo8{8wRbplrqV_1kPHg#dWxKdJ?0dPJxndXFp#49js5chKu|q zWY)XWofm0nVyxG4^q_brkL8Gb==}zL!=Qlx`NhAR>_0s?Z$?(dROATJc(#S40>FuR zy>0?9hhmX1A0X^nQ^0mU?D2U}0-K-5aURB!N0biFRzE|4Ry;S|Kt%w~1ykb$9|1S1 zzIt`J(+=JP2{*bodxN_4$IvH{|2~$+SDl|`l^0WC2&hQInUm81d z@_L@OXi7*3If@AqypXCl1g}tacm>X=buBwJ$uW~JIFrAuLd1{`bv@Q(%F?Wah-P({ zFKPCmi`CW+d} zu9xQ>cYy73BRcez1zR#-La#ksEQUA7y!k8GBB+c5WxBw-T_rG9G8Hi(U1hwqJ2|FL zYbQn!IUY)jMWMpk@KNanHEGQ+a+mok7*;h!TJqidSO|yg?47uDl?=TYy-pS@>MJ*K ztScnn0?f)i-B7GKb-=ey-XwB>f$!y%oUOI`Kl!t@xsCIr%l0IK;$KPVvop`u_-AC3Ba`e{M2cq z5M3>#m?Sb@Xh1`M$KNhBx3}ygkzT8TsOsde_JV;IW-f=Eu8iYo(3?&>5Glf@E#KJ{ zGZ+$g@#eu9!@-W5-MBRv{ER7kBQl2x(mNtgL9gGGWEQSL?Xx6%dzYU*ZSDBLT%OaE zqWl_0psUb|z6Iw}#aAO=ddrO6RF5PZi$tjH>;P>&d~GMPpwYJNDSVEx+stFvm2@1> znRswObo`Mi-#+oPo_$=CWUH&-OD5;SLAdBfqJ`S&r3{g49@GlMePdsVXIyT87#Su|R;c%PQCIZ(k#|26v8Kf#gGTqO6&qN#t_NL-QLZ83Jrn z^JJpqelj*`Dv5k?VlY_Co^*^(=1{SbT%ye{k zba?;Fa&gfrx!W1jN*g=r8|gdg(<(X}IQ;{lCM`uPWo%>WWQIr2#KOqK0}J&pG+exH zcKU{v#!h$!#-`>r+yvJhJp_2>M%)Cd%+hqyc7n!c=3*WW#)=*?N`@YmhU`WJygXcP z9B$Tj)<0zM+^nr^968*$3G|I@4U9Q{^8WzS65#!_iIXKa0V54PH7gxG0S^?HgOLe` zf{@66cKRuC6PP(U*>TX)y1Kg3xH8h%I+)VZv$M0)(lO97Fi`)rpmub(ang6Aws9o< z7X~3?M?(j5J128n8@zvD)HkqocH$-=!28!=tnL0MUK>Z6e-4bs(AJvPP2Y}|o`#P0 zABbrG(evLh{paZZ4f5aNRxmd;b8`Iur{M6Ir0!6B{hU}cr^f%kuj{4a6&|FY}QC8-%Npsxs{W#1FeXazLT+#v7xPz@xN>UBOUv{n*g^g?}X`yKstobYxjs>9iawN zO_u=>RmD5{-?cWly(EULwZjPWfwn!PLTj79S@LdP-$^jDh?Kp{njDziTLR5`XJyRI z^?y~X0B{con)`wA5MuZ5CiWuJNYTW`1gUHGFL3=WxKpLI?&~Xb!rf zqU(n;QImis+9Ls^!E@la*oLfICG2@HjUF3vXz*q@l&{bocEp6W4p2t5KR&SM_=bXb>d4Affs; ze}s4de4}_VfiQ<2jLtkILF#~WP)pQV4Sq{h`SVQZRxJ&)u0?2r$fiXN;UUQ?t+f#k z)93F@S60Nz&o7?o9@)?C@0R1qbauz1iHUSZ)2WFLB4~O72fX;xBlDlH0tOP@dA>ok zfc3fNO6NlnL!#6&3u?sg&da&QGs5@n*6^~n@V~7e{mJOm*v}1>0P>fILgZ`0lFM3Z z4;Q_#AGxpI_iY^V0`&9QO;__{r2tq?6+jHi)P3Y!U*B# znuJ2EqQ>PZ#j#f>jqnXmiMacNXds>Ty^sZ^OnZyn?+?aFwL0^%sb)V*vveS z+0MHdl2Z%5@-%MJA}2#&J~XYi1~&WoqMxnzc4%Jjo412MXf#+q@T83^M-Jps*me7ybU1mYDN@3zE|0l#QR{-(WDH*9>^E*|#2Fvx5WGVq+> z3r?_S{3-rt+ke#jSJ`i#IA39OA7tH+-xt0bsXs`4p=vpMEMfnHf-j>Gyie5!(T(tq zt^bHWEwJvpjFP0^2ESu5)1SEW(_iic+0l1oGp6I)g|BydH$&SBRrz4IEs6>>$=OfO z%EE8ks@kA!0)OVeyU!#tjNKB@u;COlcNN>W8G^4weNqR@C*;JRPxrN@kXPrOvLDE; zcU0PCZrr%p55~>AW`vi)?+Ro-x)M8~tg8#D@Ak_);a{Qh(wi}$Ssx^A4ClEn9zUpC|sX`iFflDtN>* zINxtTCL)k1u5p#Vrh{e*{Kj#yAv10qnP=v3RYjC$*xUl#jhWGV#2=`Ja!qBx$~_uo zOJ$Uc%)pG$Iq2Ile$A%x096#`V3UQBk1Ctr1&e2H6)Wqyo@)lyO#Z{eSB&5EW8Dj1 zZ~gI4gy-MwpMQ-4E!og5qz;l_6%=A`n5Q7OtQBmj9>WKFx zMpBb=sWX(7mltHRoTd)QosVU>Z8bh0Fd5BN_Ag3ivhI&rd_6CFCbOUMPc5UmzBQhn z3EY`wzH2mYcV5p`U9~zb4kHf7Q)tvX&31*+o2PAUGB(*N^w->z`ywDsQ&Xd9aa0*h zoa|@I;)4l8;Gtn~9G3Ka`|!5;YR*P+cU%q+kBm%>O^Qm{la)d@Qw*BYq(uU$>_rAF zypc7PCbtVleYV+;VbG0rDKV-_={0`-YY8_UGqZ@KDaj$n3_1wbO@tXH4*X1zk{>Vk zdZBAtDzyN&^s)$=Oy2@|8^+QVTZ}nnvTT4;nRM zg7^>q&7FD%l5PYc-GCyMndJsd-8>6Lb&nVdsEmjW5z{rBs+4Thk;;>M6?fDyv^ITn z2f@r4b;Ik~spuOxoC5Am7OnZC$BPtN-Ex-E9h8Cnj7tv(V2c}!mLc%x3R(68F6;`( zL6bflvs=2QitVj=XC@DtDUi`#iMt3HYb64SB)CURGDMgAWE(7S27U;Fl-7VMM)4-) zHjtG2pt_CAFrX2#u-}0@fZc|;Iiu#%c2S^Xykc?vvTxe3kKT=F5N3j*Q0Vl^hSK@_ zAYEK0FSU|{8^@aEWq(cMgHeUM&g=mY6&}e;56PzHNdYv7|chDYJ=PUY>kdl+K+mS_;ub zYOb4tWoiT971=CD7m_k@E1uFn6OuM( zC(Q||)VXf4LJ7}Csd~7mFo9%ly7gxqH#SY0mYYUP$*a9Mc7}EA*FVQ}wrhIvOGL)x z%E8L$v}h7(sAYt{K@P{kAf-E)3!qbPLh$<@QV-w545$Xd0fM;x#bZSPq|L@PTPg$7 z5~N93H}%S+d>ia~uY0c>s=Cztz%E17eC(0RavOqR)f5+v%QHc0(Z36-O@ykKmRAvZ zDkT2+h;OZdcQAhh?xmxv$ayr!oMW{Wl42p3^{3s-YX6}cZ=KCiX5I$0ba^+4;yu$@Noa0eL-Sp(J8GgY@$m(j^3$k`DrFVt&l{{ESg#HRL>eDa!^V4T`5YDnFe59BXl8F8YjP$?-0E_Zny%LYSZ{4BB`F z4Fn{4?g~@??RPN(r?l8FB9CMJ;>wyqq~ez+SWEP5b*&ZMEHVVwqyWTQI{&s4&7}%z z7jsELf1h|2`eVAMC%3x3k@IL$NUOd&M)C8X@GKE*wj?dDy=g!pYfQX0{PuF8LzCrI zsFOj-$b{zOz@|>&X}t&qGx2FLOX@YvK?`Vu2rM|mF69}3Z65g5vfV0(tY`c8<)SyD zOISJK%|t1a#pwvsG*;Hn;X8jIePcCsPsjv0Gggb@DStinh2|Ob2|*Nk_Lw}#qG9@| zfO%D2?wPpex2`me)clfDZHYOVR6f5C!Rv>1((JceF}oL@LqmHWK1up_%NQM@?GwhcM}cWt4jn@#|W438@Y{Fe~4C|@bY%dExT zkCY&Laew-@vsD&LK-5nQYYqovXO$W@1%!@6r-_4>m6w*)!U>zFkTMr87gbIvDvEQ&h6OE$TspC_euBE37qP-{ zZl2QcU%~YvsX0F_1`;-Y@+#A~9^((4BjdvKl{N@L{Bd>LC zu)ItAc4*dBS^e7uqWa8Mufnq8fl3P#f@EAY6bG+%#S>DAg7{x589-yGiJ+W%AK$L#-e)oQvej?qu@E1Be;)0}}r|O-Wo^Gt4 z!qeBKo|7nA7m#liyMBMfKK7@9JqXzTWIxigob#=FC3CE0VM3e2u@XvYK3#0PJo6Hvy z#P-+8a4*GYQ;1C~$rj(5QijA$nO6p`*yMykjF|!BU-z-iwFesW&MIO4sCtp_kP`Z@ED%RP)5>+4jhoml$I_rFR3dbn5Roz zKA?xCYm>q}VrnpONwYSoShZrwFlJ;;WG6)8M1l!}Ct!?<_&eB=$B^Kxu}grOs~#~k zGLcmhmqN36+n%mmDZ@D<;(V`sxu4z*(Xcl(y;EVpre0p1FM*9-7MW(i*qFeVZSse= zr#!MQQ((u!i%>@!D}#WFMD1LAk1%C(FwOBZnkGKC>1$Xn%%Ps9>TkJN<_=Z1+C8ke zBmt}!D7)zl@Sny>XU5F-k&6}jJc=UJQzt60cA5A17cvvpcTP@q&4$cRX`}p-%{h># z=QYd#TIn*#;4^|s`BcK>Pgn=L?4DBxldL&`7$rv^t*fb4ExrIAcN#0qH$ZPmI59Nt9X-o*Pc<14Wbqbsp|BsbRiT@(m<+{XFMZF`25 zXu8&%wZa`=bHVI;BGoQU!AQBbubM|K)F|v%Mfkd&(Mv}a@*QJGK7x;0^4dogrv+_I zu+rL&ftSpi#(nh~x|Y&qrV5`Y35>(-)xMRpkJ~fqT_;wJ7?uj7tV*e2XW|BxNc1Y< zKV`cF9<n#0J=_ut*f$(!O={Mj5q()K|W6W%~U zYqV~tQi67PYrcuYJ2fr>WV%~ILGM>B&LG4!e6)c@h0Mgf$Qr@XDeYC9g6R6-(DZP; zy@?j!K*)4R=#P1{yu||~Rt%g8Vq1g~V|WrD0_jxpwhbyCZJZs!j#!jAis}^bmG`c= zkY4Q$2IA52X%l|J`1!;RN^+q&hLa9y?9*dfa(Q=!02!?aw)Jui04GttlZTQ${l4*z z7eyc1LVqMU#>KM`K@w}s{;eN*g19EzV?sK6Cch@#MP#GQ?1WxbtZ5D`GseE7CCYe% z(c6=JIP6g#ch#rv4v!ObVbvb-B!@O0{ux|d@;Im8s3Gfu6*jss57i!@jolG+G>3i1 ztR!$e=b$mlVJKafY0xrwRhT<#bIMw$m?Yr75OS<{(YhO3x2)&a=7hb;Z(FNL#Yr9} z&w>An+@5xolwpk4LH5MXbTel>!(USF6o<0|_^>5&UH7Y5<&Ow0Z?t(GDc)g;iH4Z# z+;5f;={=o+jg^HJ{;__H)WT)XvP_rV@EO_@WfR7%s7-WE@iwL?5<{M@2Ov&7VcDuk zm0kldHFJpM0u#{Bgq#xe^w`gc8oCu2;gG!Dh!x2s{z5afMsEP>ZR6aViW@CzZerOe z<#=G1*Zf)*ZgJasE|tF}bs{`LH9M}7=!uwwG5rmGXnk9nGw#{&taT=jZ*lKiiZlp55Wp9nm2Rqw#MgL320Br1w@|0=tgjN#ldhgiZcV{gZ@2-R!n#pg?36;8W{ZZUn&edtBP2Z`f zJ_%nv(!7T34(Dvq8~V-&*#SpD+v5tmmX6@(yVTd?1aXOYg<>i5GA410l(pi;IV|&r zBJpWS-;}Kco|NuEU$Cl0 zkR=}TPKpiYiRP)N#E#IN_x5YzvDshn-WOqwGJld?=A=8-riL_Up>K}e8~HNEcFVmu z*Z=m6c)a2b91b(+3{Mp%*5fw&MA#nU-ZPj}R2VXv)8nFEPp08t^QqAA%8VR%r>#Su zygC#{YY)j{ST9UIT)&#iN)R6UJ^bpT=<1WY<9;Ar9jjlZ|MF9Ur+o?L>YEYLIi-1P zYmD%Yb-B|ZI7dIi-WfTr!wG|itqk*~7`hSg`rTP3el(7sS8sAIdl>lxwLJ)KRK-Kv z17i($k2kesj1-n}Mc~5kdbX*NqB&*>BjaGZE>g@OS_u!A-$|1abyVj-mGIAmu+)0+ zW*4}9o??7*2@r;P#EW}6@OOTE`Mb0h$&%27hl&f*zf#E7`Tu!K_XuCY<@?B z=XspENHg~fG^`l6TKr}-Zktk9Gh}Pi^Fq}*iO%fqfG+Q9eF9#iGz{#ife%!kL|Yz5 zZ~aT46hYjbS9U057*BGlZ+{a7;fs)!>)lOL{QfQed;53p2=(715XWNRWo#b5uOpERpZ`d1V(MBYzKNr0O&fYc15KjH4X64qX$RxHZ7+aX+5Kq$k$MfZ>f zbI%Wy@0jmQoq(S{Oa?QpS6De~9X%eugZaH6V)e`rdSvwr{^(4_U`ZqTh|*=l+{uSm zlDv`?YBkK-B}u;T7@-AaAtoWq@zC%p`{dlozb+^qDgkP|B8`^C>y$35`+=l-y(uKa zd0{fmpcjpS589HN)eezl>4VkJm{@z~m5-PC_D_!@?8bsAP8^C<757!}hy_F^D@md}%%3TXr=dzDHyiW>KU7jWz@eh}#ZHk#!ycKPz*NHa z!x&bP?*{};3UxJWr|Z;QAzN-Y1jkmsv)$BFN3nd|aQ5D)I$2LJv?vxKgIqB1x6mjV zdW||RH%KOoDDn|%lLjJthV=2O@)Q~9mYovhiN?~H=FTaiwycJ{P4J zNQzRR$-{R2;QG?Bcsf%J^YUJKLUp_ysI@e!`h>o)<;oY3B+`1xM@T-`ay4078VG-0~|b>Lyx9kf*jziAn7s!#go`BT{r zUK~9mu0*Q(B!0BOS#h)maeT=LaeH-Z65^2@3x#?da}m>KLhZ4?E=IQ#R-!c16LrV8 zQmKp7#;ujWMNz*zyJyo4pE0s&Di#kZ@FcR?elare4^MutG|C1pWg;A2yZ3wTjE)eVLs}CDJ+4UX50N-Lr>{exO^YHft|AW)7@=}f zBzuPk*&-2%65wTeE~jW}6g4?Z#*Gn0RG0lawBqrFW{b(qYBvD1Q0cW{F2l&Js;u{| z0a>T}HElsonMa9;eNRL7(6mD9&>uR928irRP2!Nw)Mg2EHiEjuu84k9|CdHqW@XZt zr?pFtTYb7ki^B#5oZoDH1LlxbL&|TtOs3^2Jd^X@2fw&iVoTX5IVlx)OPBNoVYxhS zP|u$x(>=&IvT^inuhzTRxsF|RvpgQ%9NJ}py*!=TW{gB1oLyjT##J=%m{!e&PkbQW zOL$I}2k;x}9qJt*K^bBgqjN*n2cfc}*Xiz>Q4k68S4BmW4d37p$PEt54GDVrda_9f zk-ud!1H;tZ5F}6u6O1sV14m-0SDkBpT;xyHPIvm0m)}c|nseZ-Db#~#kH+nMvZ~gJ zU5RzcZ_BMHP;L>Y87qV2sypvQ^y3RB$2yeQ9#_iZ8==PMr1>i)^m8ysyrWnf65#dY zvpHw=;7Qs69h1t0u9-t4$&*J&@5n~i@fxI;j_>Rp8C9^f4U*qcWXrma@dTP*oXDSk z(*{qA+ecoKkUx32ijc<+>cIcOEN+pElGH2~C8p7qpc4FGzzM8W_Q-vCzZn8|-IJMd z1RWOGU@IB?lo$*%5dz=U4IANR!+htWNYBg6lm7uPyVr zx_#kwIX)Z@iSp{;#t!X&Z}){JNTd9HJQDuVW5#Pm(tDTC~gyJ3EMN_WenpmRuztt<1YXra?1 zkt}gRSRW5NJ}tk-(m)AhwF@W^&CK5Zy(?rHbOj%{NKx)=USxfVx zR(NOt3Z%fQs_28sDWKlVq(@uwv(1-izmzbr zPIIZF-Sl$9ORI!%k*TygysDaPaRwLV`g~mk!S-V zV`MI$}1NbIrH3w3AM?zyHNh8mmT z7y3)00XNt`RVuesD_0`Zf2Kv_%$34c|+wZj&t+T4HpK2?AaXlTxRkpa<7;nUUl*f!F)d5Ws|O)a*4Lcj1#dpT{EK@ z*;O7Wq%>u}?QeRBP$;;>g8Tb`Pzk&X#H{qUc=M>KqtAiCsLN%xSf}FkBs4g3lXLOi z3a)LOsDVTzpmLL`r}#J5wwW?k77e)QGkDbO6w>o2T9<3LTbCaiUol(E>#2<_?WpRg z?X==ugx{Ra-{-bQJx81wrki;W>zs0Il_x~@8?HKGS~#aKrUZ+aj@yVmyODOEAEg`_ zOoI+DP&^XkDnsovAEPd9xUD-h-&;DmX4m4qG5l4m+?!Kt2$NA*Xv`e1DtGQ*pnRB9 zUw`vJw9HFuzmZsr?0mA}?bUR1+NY`f;#~AvNGJIK90eN*^8?;x^NApCwwl>f*cbyK z)}{Yqa7mC_DKj}h)7$pJK`$^_@}hUCQq$-dH>$t)`Zd`l*+xB3eZ3Vmc;%eJF(fRL zHJ`5I3;E09XW68%&h~KtF%xTq=t@8&(dw-}$Q1qKVG4Quy7lhewQln?_v`6qh5KS!8E_NSyfC5`esp**p?o7i|T&y=nupDOKY=P4JRvjh_(YGpK2s=w`n z-6Z=Oo^1OZ%hMN2D4Co1nHa-{{fL9KVVA~xgv^}S^Og<9W9*(U-bv%=VAL~H0FM{u zrZ2*4=05Q*YxHqT^s?Id4$Pt#giZ5KB82ni(Nd+%49+i)4Fl7EzkS8t(O$^TEWckr zk3Ms}5Toj%ivVRjs2P1(!;1ZdD z+#=30t1e2MH6^;L)yl{f!tKS(NE8Ug={YcG*ihtgcBEvQ2m^!9T^+)DaG_N|C`SLu z!&+qelTL;j{_Rj}L2^RJBQWDoFO#Jk%J(JRn3^iNIq&aRrzk5y9b5bIF&l=76{pEjCa@a?T* zX{8cDR*P3vQUPIFcuZA;yOWMt#H>8c`pXlZ8`O(fNbMfH%eE5iF23t=o3P1Mb3j?4 zfr5L4!dg<$uWN2s{7`V~u05f;+!&U9TDNC{jEt@PC(MtNJTA!x@N9%B5PY#X1|Z$~TQSMr z>>(6$NI|J-jtGc?_%s^Y*qJfUvF@P3lR5u~QjeS9I0bVCU1>FK*eG^*6sST_XRa|b zh$d?IRZc=d1zi%KpMMfiOc~e;V7KFKc^B9ByY09=(r`8)bTtRrluOGCfa^K?bG#Qn zu8eh(7pRqDE{y2pJnRyhe=^g09X%j}wU`A$7D3Q8dj}aNKz?zQt^i6`I6Mg51o&T2 zP&Bnv4a=%^s;Rdz9x4%UHJEw`$`HeD_(*G)i_#gjVIkN49Ap=)j_$vy%CL{df}QIA zM(#U3Cm1Nb^C%Fk&HPxae*-n>5B*lDV~<2DJON16&z8eXHP!Ko$$4iC(xAA-PB3XM zJX-BmDtF9UHS;rB@Q$YrNsfV!$nJo=AzNG3ueN$iK_NE*eWD>lg~Eax8hlZ^OsCh6#_pDd~u|!|f_1)W`%o5eKJ52?J4QSgMzo2`iCG z*fUBvR+Xh=qD4jGsp@%_5tD%W14tcp*c>Q6V=9yL>)*;g&)3(w*(IU~- zu`g`w-t&79A;RM@f;-nj$D63e@6$>UGk*hYt7O3$2qvCAhbFTI4Lj8(B3K!^7=xM3 zl}i6I8hapZSSxrl#2*Gy1$}mLV-0VsnjGj8l|GSp6-m9@w1etAN_=1=PZ~c@EQBsd z6)Xim+m?ET&)ZJZ z@<$Zsa;w|J#H{Z7IW8JC)z@bW_Ir1vN#1qdNX};a^&n?(uJgl|@AH1_0F^d?8|E%< za9vMuJ@T**j{Ob1WEM=Gz^{3;C^q$Z)dnh(d4@=lCMub7k})GLPdnoDXks0Nl{YZ~`PvHXY_DhQUt zt4}Y`E83Y6-i*WPvbD>;9*nM5>m{6#F1K#i*Dd+6v-i*RRE{)i(!VN6#un%bZyf_& z=BwyO7sP-JJ zrCAc@6Kq4uui@u8aXNXwjqGTc#ySALg)4oIRv;|Gq++F}f6wt?O^z4NVwu3c!MUb4 zDrgsLSL-5o1+Rv&*q;}lFF3Dxd@h~X0!@QjM~e?(z)m$96H#DK;Jai~G@K{dE^}X& zFHZjz%Q4t5mNH!3iZ=FSO>y@hUNqSPq}3xBZj`cmDp>ExH0VAZ@tTi)B@(lGbU~}@ zax+)0>QVehlKrz#4fkH&jyx4=?{=Sd>|L1;AUK*xNZd&dI_*-;7dl6+nY6+8*!#{& znFYe;pB=*(Q7OWP(9qLU*q5)74O5uR&1(v{qEArW6XPT@neWo7h2?$dh{7;{_9G^<|@6;#&k6*=^=x6+qV8z-F0LO z|F!4(au`b6VR3A@t$q){vD|*NZd&ba8H{GB8&cG=CAicz^iA%g@R7IjIBvRA3^#jZSt&hTJlZF0&3E6%V`uE$Zmy>s7K%vX8Q`>GN#ajB3j9?lJRDf=EL0!0Jd$i1aYz<(WxxE<)5G zxcVu?>-|R9=XM$p-NdDCIuekTGm)wX#v*e(V}?Puzl#D=RqmUQ=pu!mvRJN^uef72 zC-AG$^E=l{E>XAVS0=IM{(6q1=%U_g)F}?`Jx>DLwo_n-qJKpC&k^mZ=;C7NTNc>f z^{FWEoD&M;^(btd)Wr(bv8cU2W4}M!?rbs(Su-|Q98ay}aCqjNLmo|D9!aSnJ;VGW zxdf)!tI|+^30UZSAZ-&w@>r#Jw{9b%hqw@#LnwJX98Ed{jjrOKEDIriG-S~v4WqL8 zlKpwV%6xzGRlPP#Hfr+SLpne?`5scm(?bQ!b1AYgK8ZMxj71NOZ5C-tFt=uuFn# znR=L)jm1)#?_XXf)d!+ntN_A0L|Ev18C`$Ym zxgbe!95+VwolPP>2});kUyXH9Llt2|B21tHH+We5-mrK~B)=&af!B2QnNj;`_LEV} zX#n~tm5B^Nj+Co0TQDiCNIC96X7x8%x8<_Kx=56y4kOYZr+Z*6G`#qFGd%5KLabJ> z;!LgIoSMK>)#hCO$OPNL4Vt<-T}G$TEt98SE{eDBCrRfdS@ec$kI(47u{5tDPYdqI z(;beA_Sik8`{6^|ZbfZZ)mFT;Xlzp3XLH;q5p|7Aq4rwIbhz$X4mGz10s%`0Qso(7HwO=6XRlGGl!@nv& z8X5FflKsadT+-xlF;sSyvVYbmkAl|s(Qn5oYMN~8u8pthuc}red?H%FzQ!RK@JaN8 zD?vmhx;W1rnVcNX98(~{l3+@hSkm{5C@pjPjKtC93n6bwU{v1Q!VpUuGy2r4^W)g0 zCtCRL-ncpnFy8qE)@v#e0@{h6o>SHt4trAudu+UBuNw* zmLpT9$SIYPM55y%%We_RW6y9DN5@J+=VV;Mc%PRqIWzfRaAvanC0O70}D8#>l5H#Gw4xz?}=n68O96i z&^M$Yvf0{NCT&M?hDl-S0K?>J5fY*)gH5Ld8KG=lrgn&>*Opm&ZOPL0_F9K!VGQdQ z(z?b$Ix;jU^a>omqnbj4LW7(Iuj;Hrb(Q{LSNelpS#qkCSw}%i$*C$d@m1p4MduH3 zsxz&^QEwzII+P^jDRD!jbI;DX1-cwz$-u^^ay7|{L`A%U6|}6C31_RaQijXcWMX<{ znu(afH0&G-IwHKQ<}+zjp@Ol80Tz!h$|90!B|71WSP!F@L6z+|A}|YtsfL z;&v@Z$RM0V)9&ShYzKozl)7|-9a8BF(7puX*T-f8Lp*yVDvre9+DS8A$mYPgj}NeC z;!AETzP9D9;!nD}P}}c+g3uk=$J5{Jx%9?;SEeUyK=}6W9{w7h{0r3o{;Jhapl`f& z0Ilv`+WUjiD>`SMy>8Y`KiOaWtn-5LC;&S0Q}FiH#CM=+ZiJ_UCPaea7LHBH$`<7{ z1uHzpssvtfh$={Bsv!BQu&Z5iL{T7BFdB@33glH9kWmI*AUt=N24#o_Wra>1=~(sk zK=t)Nb@gC(yXtuTBzyA;T+~-EKFKq_GAxLAuE^1mqqpe`^%XidsUy}{SXpW$DPe=F zPK~XuHqn-@TwxRi2n3-vtH7-0b<)_0Al#OCObv4KV608b8l+jT29`hFhmY;s*DvsU z`X9mbj!nZ|{WIZio&m>n9gI1P+Gqs~`}fcK0v5f2U_qFoduiN1N(0XLGVIE0E?}}C zly*Jt&IjGqlY82UufwFhrfb3}w9Tfgxy48{BnG#$8vY+;uGBw&e`dtrmyh z%sREb9OXuxk((I zvj@2Y9c5sB>ioGoJ0VjmbgW#}+Fwe6NF9`hPNn>(3!EeNdhE#PKeLZyGceBM2R>jg zAQ=pbQ~zfz#!H3E@a4iy`b_~rre3dGB~GswCAztkDa%7tTrN{_c~HgWtfG7cTj*++ zvMOQI$nC3s@lkbQfeLP%OSa@`Aw?}XLF5GU!M5PSAQwbghW2T=82hoW&wud1WQN`2 z4_BX6Sb4OR9Y6x=GEIGrFjC-=cEKphCP%Rp?vajF2YzzqUjgc z@9TK>`e$E3TVh+kbL#5vvY(uY_r7%Ty984qGvv=9J_Dae$2G-PkIzZ+#5!fHFitsL znZvGU-(W9kPIMyi3d3 zWNR0^m%KGc)|GU&@ADjghD5fhqebLE%D-J?#a_I= z>q|WpK$GhHt0~_ngTc{OLMJp1#-sg(m3@Q}Bf!#1+)ryOd4X>soC4`&f_01*{zb`Z zm0Hn^?Xh!bY)=j{2qZ~=YeI+1Et5BgyR-lq+Qa!M2!dq~>bxK=t_+CbTp2gfL5_@8 zt|~M#gv3a~Aq9bBVJfKinBRPc6!H@0|amlN){^YTxn2!C*G49cmatq;$ za*IO+H>4%u8^ikHt7~#TI)ve_ehWV8QyQV(%`k!qcVMwD8c4%b*P&w&hV(jsYjHtN zGV}lqr@)hfz>^NddLn5y`It8~R%Q^EWYu6K87rzleURljpkqDM0a*-bTk-DvGyl#{ zbPwq$CY83yd-qzey|$M$IW>AJ!uTD=RU&oX0$s9n$ z8C2*}^oc`>3~&|g(&CZkD0YiU7d&La$bdWs29tK#kfTw79^^^f&e)8F+w-~?ehdC| z(Ze#NZr6BZ)DfEUfl0YHQz%0c*9emNwG1|;5KcM@7NLreTccF*qVDX}Ug| zmq3)XbIfy49$_p=vZ4Y=8iqyYX`$U|V|x$Y3h*&zC+|qTXv{86R(#UdV`lSmyW-@v zwJK8gz-=2yg?(`^tW3mAQOe3248Z3g8hBcJtgcV>-iO!t+D@KFBLmD{1;DG~_ z#+uZ}g;d#_%-lVd@#5Gn&Rzan}gg>h&o#cC1=i0B=Hy zBMg}@o%nN}{KNz{J>rx6b)x~u(4*tVqcntLs0Ib@Mz!et(UJIAv;gr>7TX^$&gJ(U z|K#?6Yx@y<;@C9q<>OtRFp{+z?Mw6ThG@)C{Ps_m&?(LbDlk!cj z*pw3ijR;}a69=)$70K2b_lXU)CMOypcm>J(BRxS7D_yY?#4r&*+fjliRA%+AB5AC| zAo26C&f}fr7rr3Veusa9F_c#AInLrjYE(^fk41Zo=L|L)jU};DnGehg&Wh#}bNRXQ9BX!9L2zDlL99J7CwWWs z9&E)^ENiD!IXooR43{ZM*pD@P+QV5#MB>wB4@Zcgi)4C5Kj0Qg+XIG1i_LP=R>e*R$! z^5onO)uzO!DzkB#C9`bV^ASwCi6guj&5p-gOmh3vtEdGfyO8?*;-6f` zlj{dt*O?d^=|;4R1It2qhBYH}zIA?xQ?(R0awZyc`67GBgnVJka#y>Zm7av@ajP6g zyF@DqlI4Nok-SaDNlG{g1pg8--5+t?A91}Dr0D-D@pLi`7cY-h2CEAz-6`>=!{^~> zvP-Cp9fn2;D8nEGRP2ihsHSKN!@Q)^0gy{%CT_T6=JGo_{#tyocoVwzsrw6Oj#*c{ zncrjBi+e74ve@7M3l?o!JO75TPB`ZWz}s$v8Hh2}crBfQw5=M*9#=81YKe476(`e2 zL?pTt>9Uq2Z{)7&gBV26d_naEyLaG^U3Q`c)`z>Q>skWjePvyX<*iL`4WGZ&Rhe}^ zhy5*YO+L?02O(peQE`TIt~$Tsl8ROGRmRokjmk~t5B0~)Uh_la1JeTAaRO#25HJI# zCfiAzPDB*JCeLp0F4CjvJo#Ri35iCTbT!qhSj;pHDK$j7hPMBdQqWY^ zxKHq(4HJA#p!7KF zpfXc?*5$>OXw14z6I8MPa<+N=)u&%Xp2?a&@B#N{{&i+FJB9WL1em(AK9p>kT}4F6sT<4Y zDo$mmi)U7zRyDPDTHU#9hd94-PW{b6qlOT@M0sj`A>#{KU#Rni8md?B&aRO0g{&{s z5oTx_k?QqqEv{wjGULpanyH!7M$L2DYi4Jbs~79bj3uGPv8&Z<^lQvD*5$RUGwa!n z>dpE_^H%G|+8Z)==y#cSg;QRdG9sO|li7rvZ9rLuX-L>y)0ix?7+jA&;_BqhNu10? z^bx7L49f5kzEqmxQzPV5D#B8zA~bEm<&(*(K%e>;)#v_A=0{{|4PE8a6_u%^Btn*p z1(d0+hHV0$N{&e6i4ENbzP>NQjG%-&4d5)~pfW&0k$E_GYj=MhH{ALEhmg_#E_`Q%kMeO#v{PV#7()n8~lNES!PNP&@)aEer@ zI|wbca?r+6`5S8S$=xW4MkFI6+%}vMY9vL`C&Ky_ATU?A*(rsao4g`gZ5?g%qtC>6 zHPLV=8sVbUo&|^;vh#QA3tm`r>Cet>n?I?z{OoTn{q83}c<3MN`90>g$F@I^n}FV) z+j-6U<3E1B_~||9P3zmY&iVT4si!TiiC)k+{-MQ}K6~M}esi61%lEE3e^ztzvieE8 zuDJZw)t7xl^7zpZMeHHHKPXBw2Eli^qAv(Ot1JFfR#)&@UGbl=y5PTgoC0NI=zrKC z_u|!Ej@!zzTW}B_Mfx}q+J!tG{lmOU{k-Hk`A>X)m%)|wWD}6jHzcc$|!BLwotoSx>??=?bQxzs-v}On8T`sy%t^> zX)5LUCQqi#Uhr*2mK})?NfOV1@nJrMF)zcZK5`UBk{3&8F_vhNq(0Xsp-ySD1n&{b z>o{MZTY%AR_$L@+vL)c~Z9E>$FXT7#d-=mW&-db+y3~bRUFv2fc_x~?VwU?W1c`WG zZ1U%Rt;Fjz3k}jQI~fy{@NYY18s?Kod3cNXE&} ziBX5$!!wfPC(eY%O`~R)d}&5_O8*PLMQcV@RgXZMp6lNS+4Gy7E3UeVYoK+SIKzln zkmw)(-F?c?^mPm74lK}95u;4Y%z^&W9_)}ke0?(qyB;~A#QT;ho~zJ48nV6s=kuc~ z0}kQqq*QVoglPe6mYcL}^e$v@gYSJdXttv`+!|BkP7~YN4QQlmF%^7VaHr?c$l3L)Mxd zAnW|Rup~PSPkuKE{4io-ydxg>4Y+fM%MG6$n{Yz?L;B7Us=>1Vw%tFy?QRPf9WJ!`dOhjH8H(8|;SQ1T>zVAWe`b z=o5{x_V}P;2T2XkCJVzW{OR7hydaogPAYSZrU;T_cgS;Y$0;;CgPOxKX*2>y>uf&v7qGZ*p%* zZyN{f54aDd4~;|iaDo1Sg%*G~JwleMM3&$%KkFibXS1rtghN(L2?!(y|1fV5$r2c> z1H@oVSx};{pcbxq7QixP8Ik{Ci-mYBXd1eXEK3jA!JrD$hIN(If{Ka+3kPK-7~@sR%3g(4dQtDL1s;<0<`tnk zZ?##kTC4>--Y zC~PAV25G33mYZz{TKW0JB)MCcNTmjQ{4k*l&>+tFRx9K2MePHmoLe*IR8;qRe?M+K zT)eF+Jtkb-j8EXFi#J_9xor-*v47@?e_(aQ*tS#=kzc{~;x7#^r16)^d*O`+LRk`^ zmn8vSNL1?H*Mt%pq9IXP>A8Il0?{c!FFrd_7M~p}%OnS5HPbJ6`^k&;Pm-72?UFo^ zJiV9W1t%~-uYL^Qx*S%#)SOi=1wbtKtyI`yK zS9(?2qIIKk`%!L1l6>#`oO5PQ(0;!Ul9^{FCo_|Cp7+`R|5xD=PC1aWi%vL_EaN4E z<2-#A9d{&En(N4GWEwAu?T)4>YL;T=&Z6&!#j)KXOif|G2<9k|AgNwb^k*+kqT@R> z-CHmaoReJWkU8YueN1wpF2W*bxt?nM*g`?X(H93u03xj?^ZzEknZ6~4y+}GR`7f%H z%I?PIml-+YVt`1RjG*`>K`S1ArK2=HvZCKOnim7@Xa1A-aj?xiMNG zoG5$5bf#5_bkz(5P25=3Rf-gv?5nyn<(!= zgfooAmo`NS<3tAs*wfT*1u01#Q5-*qN@ygn#i7THBiOi+Da@`JNBX+VgXZz_U}~4u z3FjAxz50mN(@igWSl$D;TbPxQ=-Qf26t5xX>VxfxPP!H@QUUBAz8sVc}1I+Uar~T|_$Av4%w7|%ph8N@1 z`E!b)#(47%-GohzO0Z{43V@nm{D9!6$i-&x3uoA8hZleEd-%B?_Br%6_bdDgeeenj zGa;5J(vD#jNpG+pKOhY^CmBr?XQSB+?J%<`njx(GCZf@LEbOA^ZA0srUG#!}I>Gk6 zh*~K3G{SiMP%l22z=r6l;u_j#b3=7Z8+!YJzy3G=3~`F4rj2~UrrFb|Myi9Ug-_Eg zX;M={OE!(snwmPb@sWGdbQrBCEDVq1>^44){Xg5^vB6(wMe5sLe&85XheD{ z@m%AM#Gb}i5_=ne8+pG`JTr=_N%_knNw;lRut@DBl$b@NOe_;GG&dDH+0N#(*{RJX zv8S*|TwGYGu2)}EztX-cSRF+jv1UuI7;CKw$1fgp?HGDYx<&8S@7Fi#BRaQH->iSB zGx{Fii0&-us>e(Cna@;s#0e9YC>@ZTI!}a*Hu9I|R zNae78*T{RWu*c7!`b+gEcS7g6x~@2`bFh=%)QLJ{gw2Aycue#s8)Er*ZHrIf(&8s& zEv{j4tWrzvWqvPDXZUWO=EHt{B3$NxabIU_iPxbu0`{AaLr(;7VxJR;f<*vq z8B||tC&d&Bs;ZCK#hgUiYUu`}yV0O$Zy1|gV&0X&|S+ z(3wnax-ETrdRb;ehMySfigqQ>iJp_}6??Vwjo#=*$tB`a?MmaC=rzf~%pcVKvHgiZ zhrWn?k@!p1fy_uIk>y&9mhd>P+i~GZhzH3*kh(@MsyY%(^MJ9)KR~ic-SA*bSV@S!rK7@n^0IM zs-&#IZq!pk%T>Z1C993H{WdwP`E7F6ovVP_YFoMNz<69mi4v2i=|O}xpiO8CI*iy1 z>PE8=gGfP^ELucJ3#!QSLZICUs+hz4^GA1C2lkl8#(O9x3UkKm3+bQ1=APE zB??vqi~6kwGKl${O)bNok+su`5KprT(j$UM&b0vNS^y-xV3Kn!z^Z@iomZhbWWLhd zO1=T-E~zM!J|lESY+h(yY(Z#2?8o$vnICCSnolNGQA@~6=*7$u?s|2ZwnlqO-7f8r zx2tMYU8nwqX7t*Njcbit4aPv&4LJ4VV77Vz{#YBRP1FJEFiz?XL!m04F^xYu&|+4K zW4@XjB_pSc;BRVE6ikO53HXM;l@FtGN+E;eUxbjO7u+_Ws;~nu;JK`Ddno=aUS3nt|Tc8CU=1*ku0s?qt!KZi*59q`8#fuXb9Rw4?_bZxEr^5^@9|7ZE9cm3?YGMf{(UU27gPu{-d zK6FQH=U!BW7gbA#z*4T3X;#Z?MeR(DYY(@l zzeArZ&kfH@UqLVAE|)F~FGvq&-r?R2y`T6f^ilZB*yo9lz#>L7nL?77(dkKIQ-!f~ zP8%DYNVjX#>B-tz;j`19Ap4VT)x#FrPil)v_HWJ16)Zaxy7GH1Cws%fepa zLt#Wf-Exog}pY=*5&xBRuJj+hcp#bH|$S8D>qGZD5uiX0X z^-JElZNU#)`iHVFT)*<)pSfw(W9$Cy-mjn7h?u+QOrrH;XVLbXumA5?_rLiH@y*k* zZ?49+GJ-WO3K|#7Q0WNHnR~fj={)6f<|^)5>2gJkxE$JW&JQ|siBy#ao+|qf+_CV{ zBzv+wF>!Kwl073iDLu!YpO~Az#J)OtNqQB(Dsq%Q8aJsZGPGE1c9b;Gm}uJAU~V#L z(_~X=S)g{)&ylt2d$B*+ctrxu2D;a@&M?FsL*Iv+gpIqn1lE^tWHOvyyQ3d2*}0b2I(5=>+<+8JUBPZ z(Wjg$3S870>5od6mr-K z9NRYtF%LJa;8cR882Uj3Bd`4@Pk{8+DWo&S4HQZ^!~`WA4VxgZ>eC1npITy+sAjM3 z^LKCbDeR3teFkwA49)|8@vf0$K&M7M5l_5?c2hOfQ6y7-aj1OFNtp;I#b7876%O^f zbs|Dm+iAJ5#IR}clE8~Nt1%@zMOnO&LIqT4TDuk%unAe7+D^&Q5NWEPG_aK6Wdo*{ zWaM7ZwpMrExvssfz1Tq}Ah4q%ekwvp8MkfR7)su@@|^jp39WO_+`E_g(Y<|F70>#P z{Zsj@1()7?d=aq|rw`9zKErl`uoJnpg$0Vjg`1Up_#9<&n3t*&Rn1C$xVf%V86Tde zoE0t!=POq#$K-!R^s#l#4X4$e)^JY4hUQJp!uXo;W4fEqQqHQGJm%b*bH^+eE~~k0 z%!1}M&HEcZsrg&omkm}d%13t5TL&7`Aps&CGfRzwIA;wgG){Htn;nx&rww^>ZCaJ1 zk+ysrVG#~82md`lt>V*NjS&G;(P=QV>Dih&o3mAz05yb$5A zgJ(Z;y%0HyaN2oZDCXiKuz(%rv4D*_=Dnv{imfnEo~q6G3Yqa0GUF*^tdz;UZ0t2Y zG)4?IV{{v{aE#}h6~psXV@n2@6(dR1&Zq^#v^4odE-R%0p2j|V;ep@Z%)K_3o`a5RJ$X_TR;P@02C9-ncw7T9U=S?436Mz9?r zH!F3+dTgVx1tHs25Ij5NnGG)25b;~Fb{|X@%t250^&N?kvef|xGW$H+&P--@Yb-n!i6x3L(Ne82!y(E@ zb3#~=)lu<`8qg}$k8PZWlA4#Cw(-Rg2@Ogp3c*a&0V;z=xD6BKkw_WE0#XA=?xZ9+ zPJ${j@asd}MIKH?gdN@iii*AZ;iH=0sC>{2dDC{dr z*w?Rc-W}yP@y9z%HZ#cLMRR~+Vf@#tVjpv2V9i(`85%h;;3KwbEVwSM51!IeLsK5+e2v%lYk)4{(#*!$#9hAyTbTYuBM z`)(fEgRRz`SRuLymX;D|*+tXJCwBWQtVdXwl<-;?#{&hkip&LM)|UrLwBqOKzQFr} zfQ9ml4h6ESip&LMHZZxsdRLe61>P3~ECfDjrQ=hPxq!@;%X}RrX*{{kv!o5uCTWW_ zD19g$mIO-5NXw)((njy81JZ~jXC$2P2`tS>JhNwH(0hfZ5_1cpc#dafUdVG4yOG_* zZea)611vwt9%gBZ&9eLOBbIgR4D@+yS=CrjHC84cfd!|@`c9MeC(2k-m5_d4~Z$#9p5Zv0RcX_Z8H~L>{Co6M2p$mgeKHS}02wxahsXGS-2H4N{?)^H#)_=X9 zqDLMdo`WWWzSwA;t1o3#pf9N9VJ~0MgVQ0S=S5Us(8|a7iP)fY4`yv&zaF3+99 zwsGq?E+%rEz_K*Ug(##cG!s@?i&KQaHK~JZqVPi6GB)5CC>FzhK+DVW1_fo5Ze^Cj z5L}+8ug+nr;wxzDau{(Ck%0?wps#S^^UaEGL+z@DtOllxvb`7 zY>jaKt{WJ>vUYr?WBfqdq=(ODKYjb{uWou&Kl?#;{@0scnXwR?JG}0he-aEbW4rh) zz1-E5zHRCZ7D+juEr;`E%5smy+)0;sHwENN`~?zYX#a;h$}^JBGUeh5WM7bcfgrye zz$Ki=+#u67pAA8K^Kif2K-!&$2k^bk!4ojfaM-yWKf|*u$MPN06s!*XN%Hyf4b1iO ze&#Q{@Dz{g_74lzTYp?QvTOl_6;Ws~Ix3+APJ2*rl?(>q^}bFdsn;;|Kz_fatkThnJw2KNx=O zR&Mw4m(Z5sl|u{Z%y);$K25h_|Jeat6l=ffJnKb0qaD^1eblH*zVqsJK4Q=H`N<-@;K%*xD2v29-$6O1uTMts9fH5;iq0TC@6_Bd} zXE+^@Qvo>{kgEdhl<9z+3dqTTtOiDawScS#WFsJl0_mC=knMnM1>{g5Ko17%c0jfQ zvgV-~MIY8k=1iO!idM|C2ib$tpJE?nxp%pvSvn?W>!f%pD=|!6b()Wm3`;7$6nk95hp>7!lQe4>Xhp34~L-i7TtOdPN%Ln3BYM8rF zZ-3k`I#r-pUUNt*#q%3dCu{uX(s6ol|8sGX;XRfVJ?rIPnd`Tf}x zeybf6-B#znNu6(=>pb%uF4g7HJ_?bx0-d3Vk!HY1SAD}sLl8klz0BdbUjsSfgdv4+ z)n9k*b}qjQt?EB9sBjxhkcS4^PQ5{5L-KeCX3qMSyTljWuw5tN$_wx}>1sGsA6Bgt zvbBhxVE7fXe;Fb=vMDFAsYJXI!GXw*rHUXid^HxgE#=+Bww0j3{B;-s5J?Oeqah)I zVoESId93xRB`Y7!-17RrJ=b41|FmWQYvBBa=d7K`);~1!;!Drpy?Mt_1O3yb7f*cX z$)ShoZL3zz{?P+NfAF){kMX*WqK~1<65<#>L_cHhGXKK-HFTIc8sb?JAJk&Kz0pLE znET=f;v;c3D~9!O)W+E>;-i|Z>8d^|h1CNqUoWSy>5`s{L&h41>{WrhRe`)!Dd(*U z*gK^bj)0~n1dNck;>TZkO-|YCejatvs|uvX3c_E?%s9-9kQ_FCI8HB%Z;Ee;560Oz zL$^huzV1bRZH)SHR}?Jt(E-cy=r+DJb(K#@U9CXs%6j&A(6LWUg=fZqe7XG3O=gck zIy>qI1)n(w5bNECD*0@bw)=yD<@;0LxKC)6qYRI$YOh*$87MX_j3v?oT} zx!k$(h3Zn~a_(|@ zsVc|PtYBda86H)83kNzt;d1TGEQNC^sI#R&-GuT6a02vsyw<7TQU}2Upu3d(9!MR8 zK}XN!i{k`D38s)07@<5)LYjjgVoM452~yg}vhFKcIa$-a#^WTs1}If0)m>nRrJ##T zr9r8nX73p7YZs6;@a5@m%-mlC;sGBRaHULdcL*(|74*73kqAG>p!a@+@7`T1Fy zAjTcpkjW}B0C=?mh1%%0N(0e1NnR(>NtEn7MSc4OhCg^=1_m$8QG*vpPaM2}VKeNj zVDKU{r6Z0;OZs}1d&*};`IedB-b5hxhK|zh^itods zkudPSH&{$SVb(u6@xd$a+_&WV4{y5Q{;}3mD_1@L^or}Y4lm|@arc}#_l`XB#PHYm zoHKFgYv#$fUU}o)H(viewySqg6#XjJ8VkYBP0lGTA!M?sjxDlhu=ChO>8~(X}V;&q?41{$R$xu4z97hAG_(mJhu{ynpw|C(KrS4#%<8kZ+Y6 zSmkIiK`I#?unZalOCq?{LH($We=2e=AlC)t+JIaWkhA45VRebE4cAVTrb%b!O0}2Q zu9ohTZqGdxdcOHrj3&jB@z}WO&F{sy6n!2|o2^KW&ll%Q^X2)%Lyy`ClfzBI(qy82h<0aRNh%qR z7NK`d$kPxSJHKja6!=IH7p4mHc`uv>)T{ zEwLsE*v~hSCBK=-lHW=|4JHANWb)HVl4~333oF3N{*sVuBHNp%JNGrACi2$gWtx0$ zh$fdokSD@ta3-7f_!qsu)RctJQq#~>T+lk$N_V%eX{B39Lq12v-S{7tPu9H**zOX6 zd_p4ZBp)*C`PgVFn=`-^8t{i0S!i96U@Z*$00Fy<*Tizc3XWAWYCrVLLy42UPI+(N zj3C!J_9TTv%V+w-n1w6ZtRhC^iFr$F{H?Sn~7l4ldtIk_vdzsB5X&S^NQx{eDs z*ITA-hD?U9)v_r{Y7|n4I|<)Zhw;N2y)H%7)@iCZMoyu|21(`%Y>LX5RV40nIbY!h z(v7CV+O=z`fITO*>fXu|$W1>egsPPK`l_++wvS_#L^2tv0uLXljC+#3L{HrFv7x?U zEZtrl-|-DxJN{3oSD?|>z0J7mrq!$3^FMg?(OHuwG(9ly=3iW3ZBegVyn0DA+LF5c z<%dg)U%h$nAJD1ktCnAW=Bah@eCye3XHL1XF;kd&(-rZ#^XGQdrK>`6u5Hrl`4?>b z&I{ODoAhM%!eq|H{xFQPynGeV^VHT|?)z3jEhlMo>L?Km^5ko~y zsbI)BE?^YHtfgv^_AL(Dqd%*~4q8Pcf;d^4yg*nctPwT{EQJHaO~MvoP}nE%KzZbG zA02^pAP}TG%<;LoxF>jQNXI~@N$5$!2~zy^B2YKP7IxE1s5lzGb+#3l>GnvIWHcrcE7I9eln~n-b`o~DSO}q<7>cSW6jiXBw($9<+M=WK%4i@) ziw5$_Xg(ez31AYk%NXR9F&moc<+1V@_~=+Uql|^Uwz}5|jX}{OMlwo`obr(v8jPXX z%p{=xNivx{oTQf}Hzl_uN0Mx^+(;?6XuS4IKk3w#0|&BMcvjjc9gtYb4;-X&;NUfB zWoXR;f(Y8NkWEU^2$g0gMwRlsZs#}CMmLCn+1Rd5ZzncvW|FL_YlcSfw}ed|r;eJAGHXj16oPZKF;1jpkw<(PSf2yZx|Tu^Uk~v5o$VZ=YOPM0cx}z2=Iq!kyyX(od;JqzB{|sK@1B zP&xD^L!L!Bvcx%dw8&vKF8Vuz6IKD9 z1iM7t4WM?Qz~7N`0hC`*oWy4Zo~1cXRS0e3!<2pD{bzJm#}7)HIn4(zYL6EXkItT+YrLhnwtih%ai{vY?NGUMDqgP;&M&$@QaD-Snf_Mf0nB&W_%GAFLq7-%B9vvH zVAdu>QQ#b1s1WaE)$hP&;ViJn5Xs7_?hghBbhrIK=(G^Ya^SISF^E!eK7@D!YpbTh zc08(uXjWz|*(;p8e%K3GiGr9HjJ!^Y6S}}?NX=`zM&5Heh#S+eb!dVL zgoeT)URJDnxnP~k&Xwm|ORd$`-Ii?0EVdQoa<~`fM9zqo!jTr2sL4D?{=18RCjw_Xi)2I3{@N16tYF!8ffK?UC+PS(=QTa7X}V|` zMnM+C_}2-+glEYp8VNQl8kVYS@bPRM1CV`7h-tG8!ni1hkD3}Hg#BwY25a-vj+~t( zqif|`35u6K&yi+X=vwPmi;w}G=O`wJ7C-}#!N%|D?dWLe=psle5;KnU_Qr8ifWL?l z?2UgrxrApGEx7&v;Fb_{vx|JM_duc3w`As(0livQ&C)N89KZ?X0lfbA4N&8ZtnF`d z3kcuoTZ;24{1W2GzOBMI1kcyZo4%zjNIoHs9M~#k-5=VcHw_~+c>8wXlncKh_B8vp z3FFAyY@;U7yWO`hzhn8=W5HjyMh^7LSvE_NpZECtiR&Zp?65njX8cXM-=PZX*zIMK z6$(VWqqCiV^^dp*@D8CEFkCPV44OW?XZN$+Y}>OhZfrkw$L8UIJWqb45aWZE%7w3 z;iX_e0&cVvU^T#|OsSoQjf~oa%WytB(RqRKL-vQ_qxz4GL2i&A6y7i-!-;k#nUECG zl4d)asH{czDPoKL9kxg4QO?&NMvuskC_Cw0>VGJ&>u;L-nRlhPwLh94$+lf#jIb>u zu9-e#1d$A2jF4rT|0ZL^BA#bl&In!t)(FEe32B63Xl9u)!jyS~He~Zv>Q#w0^JUJ6 zS2d*NgR~L63A7RNEF0NpYqzMivT+G7-QvhNWZ3EOv-vf!ZQdDhyYfISKM2CCje7Km#1n2dc3L=$QzWZ zPPI1H$>4ADcw0@U2^3qAPE=ddDLLsfyL=C{USL21q7g@h(?^0Md~rw9_af95BY{Z= znTcQ;kb!O=e)LaIj7>M^`+q{S${jr5n-kS5wBF-uCsdI`p4tTF-DV(Yc!8 zIn3X%&L!#JK*bJUHGd|vjCAtbTfShhK5dmzaErsO!$@p8zgh}q8+zBo=)o-McLC*Vi>CVP* z$=ED2j^e!lP(N zNvBxjOyhQgF%soJ!Y#_$Wk#b8!%$7^U2rU%2!}#>TMpv~hKk)sUXjC!B8LdPTj9wI zP-!zwx1?WA)9GDw_jUuH5huKhKG#vYZO5iBwqLesdlx!=hki4L~i)WI(&;&$Hnf+~0^5rd?H zO*gK*SXit~FD%v)HF3^dtWO3tt*3q{O{$QT|64G6*m2rUGY`a+YwS9mQYleW!sv-n zq+nvccA*q*D2dkzBp}}AcGKhuC6!ivfK!QUU;Q|oo)-S?ptxqLFMDfko_NPILWa+= zT9?XZ#E*5|y>$~_{m(a^pH{zswvr5@nSVuEi59++S_ynVUV2PhYq)^l2E{yK4Xnbe_;y7vY~*_t z`(Y2?ulNUC!wx$ifDj*66!TB;mqAXo#(BYeD zEhjDQ_tBrU85PcPG&Uhlcdmw|bs<8Wc43wX zpOuxwKa*CDC4DhLJDg0oknB<Q=QYMm9t*@6Nhfv&b z<%~`WOOg2a;=H3+!CM?tC^|l4EtWb)l$K&_BJUK-O$AHmnVnSPe}bI!XpD3k#Yg6P<)n1E%K_x&5%_ay zU5P*!#FQj+z)4=EgXXDDiz(zWf};TBbO{xyMkJadjMBw$dYL@GprA0Shnkk2(xZ_z z_+y-To4eQ4J|(WF<+GD7?jhxKq901-b1>NfRuP;%%lg0bCNt{`We!Mv_WJ~eWo=TiG~z+ly)Y^uQgs3;&FX4 zltjW>p0nwlj6MY=T(kP*Tmr{AjV48zLg{iwsh8?=HCLa^22K>cuP{06D-RYVT9KS6 ze7VPLmxao}?eLe+m^Rh?Q0k$*4;`F5@#F$8?8F}z7uUY$3Wc*vBh!VBwoQu`))aM4 z@pV%~gx|t@N&UmbobeMsP~a0}52XYlgzOW>h%lO+NTWI+%VG;>&sgm&=Ho3!- zD{3njtIb;8a$8NwxTBD_TM&rH?8nb5z{O~kTonU(fVf-fq_)Fsb{`oWq5rOs|6E+eJ3Qvm$_zL`| zlGkvK|NAwZe^uN32vzyOB;t-VIyoUczT*ITk4e_^JBm5_>5zwE8gv2!h zYC#R`5_S&J%{pX7X()&ys1TK*3N#ljM$6G1#9(el+tC}bRjq60EnK*?Zp+r9k~=qM zOjyz6n^mdiXT(^dhk4|5`${JGd=pBTI%i(CNf2z#In|psY`DFpeA-<-1-a|m4VL+} zST?D&mi(nJYjCAB^t3lLwD&MA=}K*8R#qUr1x2om6h}th9g#wKMjuP)U+j;}9FBLv0B>fQc`h#jEqQGKG`XAsJ{GnZ}P|D3({0hhk=1o{k6) zo=dzfgOgsH(_}oRo#Sn1mr`AS%PWV-xHy8^AK2*ZKWUPK|aEMyXX zLR6g+*~pe9z~!S+h>TvLjetJMtoPK#OLR25WGDEnqPV zDm5ot%mAahfLERc1&2^%O-89lowPXCju8KYfLNWjj$J8BCIS@uoxS zqlQ%{vbJxjnZJ0!cJVDJ?WidgyY4By?a)2=dHL*LmzU1i(p5PF*1`j&QE_cw`P5y6 z)?X1G8wss>L=Xx_915|-Ng*XY%_3SL!o;^n-=+pIXfRUPjhTmRqv8(izm~ogrh>P7 zo_JL}gc$MHr0!u-cQf)5U0WG569kV#7KwKuh5j>UP8#3TaFIw1b%(h(gRN|zpbZx{)*Gx zIo^y6Z#0q~a6VWTiezWT4r67c^Jl@_*3OBcL!D&>c~dq#aIwYeh~zkJHix)xd#b0T zG~Gp8z(=G`8Kh1&0&A;dTFOdIDAjHZ5eZC_*r|{!9#uTAz@Q+)@1R1cmyn1#DTLo< z=0~(zgqI0ekUv%#(q0KS$vzN9nn`8Ej~TKcma*1WYS`9I-MC(ij8B_ z`phN^F5Yr>%jB}|vz?pIZZ0Y7KGS*s;em(lJA5BIrRLsCyLY{FZ%xg;@9f%r>E4>_ zrSHD}#=Gyl`TD!k%rsKmrEDS5F8=e%Un)4j#G9ZI_GQWoOy+4&6Z9_$0YolENm)Ez zy)228@zOIh20KrDP}s#(7BmK)&)Qu{-rOFRImVFky&kWsWXx2lm z9{RPgMGI9tRI-pB%*aUX+$V#{vR)Yu$%yt*sWRUR!tvmy;%Pz1 z2o?o#5DcA0<6HnR%F=@dLr`$ph6v4q_~p|`Es>7Mu%Wn^u)2{7@koMt2KpuWB#MW& zqsH-<$3tjYSjyz*(VWZjU?~$#5?ZchwM5|hE4-C8DNnC$_>!3 zfqpf#FwlfH5+QRJcLqFecUB<4b=qvY(yUH`O*-$=!CV~;CdKF?Wm%Aw6-Ffa{R|wONGB?&$+ghKkS~RI+rrACAMbX#LSwuSW3)qn!356 zz*n{~r*ofi&@iv-$l@i(I;J!=!4XYt*_QI=r+TJOT61)n{r-D1=iON`rEOMNsd&U* z+&Hsf(d4vyc6yfIyF5F8Mc@3+2Pe{&m?QSGli4VdZ!M~bIW%$=3rO+HF6|yIZXvFj zjBQs#B{5<=5%)7HnSu!aAh2poXj4Wk=x|w-)G;!WOYG;!urQpPE42ZyK4C^ZdM~h( ze=!)p6Tk4lFT}l^=ofoo&y&o->z#OA{IJCH7M5rI#BaPORym$2IaLa-2ax2eIpFrjzA)7Rf0ml|@mYeGwe0OW+U_p`vu&i*{8wX%6=v81K31>6VjSG zQ&MoJ5EuyHK!DG7cWSj0I@5UI)fN?Et*%hWo9fbYUKcmcl2L0hM8@?<<2aW17i?(+ zR&QbnQ|OGxd>ZRAfdYfKu;o^B$M9ej|Hu26#cM~mfAqyqe)i?%cbfb6H@EcdZ`%Is z3)^-*{xoB+6aV8C5zxi`?^xOCpFj3*pFaAV+0*Y{+0?gZ>Duja$K$(pJ^fto_UDM? zE)<(2Yi&b5G!SbnaF@GrwF`<}(4Pun3#3>;VS$Y%XfZ*(9+prN?bJfK7V@-Et%PQv z3erU5CdG&Dt%Le5G$9?FiXd^H$G=A(y>K4&LzKRa6{zSY8$(whkKHa%}KvgEs;s?C_{EL zJ+2|=Bkn13obm^Hyny^}m+t34W7pfI^PPz5^Y$Abb8ETx$#W`DZ*2Ddnb0#6+Gap= z3~FQ0G6@!k;EoJflmQhkn2`$Ab_fZ8Cb%suxGSKdLR;kycsx@AT8}&GvRI}$Tmfd9 zi&ZEH_$E*%DZ1b0OmuiO_dC4tcmsi;mKnohg#-{umX4r?F;k~EnOqDI451|!lIE)- z){t9!MQ7tPmTo!L-2KYV8O6JQ^XN;LGhMeG>{x!__Q|@Ro9gd>@4zD;++Dya42~Pf z*S7so)vCKHoq^l#s$243_S}}4*3iO87RPT$OU&1_2Gi0E~s(=f$8P| zatm(kc8Ag|G)a<9nWn@_A~C~6V^gOh_a;{N=#!E_*ZoD! z(J^sgk4Kgdtlas`s^HIGb{pca~I$DvpcST!VO)HE}rU-J@D7T z>(3@j!=ECh$wTe28GCYIa}H!oD4Kv5d7<136)8||ueIZuM1?D0vjQ^MA{INMZWM55 zAX-wC<#KvF$?|5XsfZ6tB__Clco-jz<_gs5`?hfZ>+)O2>*2lmJ6j#D-MP5yXoHtj z$yvXCPvz|X4fUyfu(^Bx>~$A*SO1*+Ue|TB-uo}AnKrXy-t;xIG7{Cj^#q!UnMmn; zZiw)qAeOdY0X+)HXF;cNQxKqXA-99pN}=V|M5M>LkgzjSZ9qTP=4cMzd~dR?>S0;d z@RSf6vec`utYL{Z07?xr<|j5C3zJsiS{_(Kz@o-KyK~t1~o_tb($@sw4tMQGW zf6fh^`sWW%onn{K`#w&jZ3WG}h4#ee{ga2!m2h5pnY0@v;^n-XP6Ji){MQPQD}sv6 ziay181*cFLARTgnQ6l23VQ?d*iQE9G<=D+CWLPc-8D!UW(0HgFU+{bSl2C4aZJV1G_2M=&7#A|WGtFPiu0LAtAT3pQy#b@Ec_$(=& z>F=0Nh{ZIc5Ly$fF3hONz=i1*>A1*M>B2>}N*gAQUY)j8i|hDS9y=UnKbTC3^)wLn z`x4=6maABmS>|>c1i8h@$W#<7Q58)7$J}2Eg`zjXtA}us8pMRwjpkaT`B4~mGidm0 z7iK8O9ON6 z>%Lx_z4HE5%YV=@rDV;KhL&T^QEF-W#a5V-h%tq{F%ygZGTNo>mKLTlS~*82>|7b4 zB^{1aZWFrEiTnM7gM(r#_sTcZWqaRFuKfPH#N)bHPJ*%0{9dI(j*(L7rztEziTyOd z5@u;EUO5I{AtRs!Vct^ZX2XFaPoBA#<9)G9>CpG#}C zK7J{ec4tbd77MLOvg@OSDyERvkYTZ9Om{ACj>rdLVz9`o=a`c`pHsWJf~Da_h`)t! z88?x%ne>>TQu2O|#VQ<@alB08^Y935EF;6jtxC95`E*n%d?@{!qv{QRP!A(};`Zc4B9yOQur#oF=PM zf9g`^kSZ|6o;kS;<7M*)Pu05E~a@U^ft$m=Q>;>cdQ`@RD*wSO| zZ3h;n4{9bZu9>xZM%tkL_NTgM`seR#bUf{;>8*co$&%@vCmL{9{QbJS7lv{g`xasQ zSievz;ed?jta=haxH!@1QJ#ICtK)W;w3ZmcXNh&O4 zzT1Y@?`t{GSZvHX*0kcpx{|3qKVI8){;p{S8%}RsT26cV)N=an>Y9UZ?Pz}W?T>e?_~v4ywx?$9#@YVRtUJpqw=Kz|R3Mly zl~^@5v1{vNRSi)nj#fpfQERb6yAfKo(5u<6!D}>d5AiTiO6Nc}WM>Nncer7Z8v<@{ z6H){^-2w<<7Y%9TahW+usBV%VN^9Sk@I1an1W#cpS9q%qNp|+gjmf%?bzwkS-;CBd z#hGcE?1!3Gp6Do<-uuGZu5(*sk@n}dF3m4(n-$KeYA&6=VL>EoUdO?TjmzhjPxWL^ zpT6a(=H?f6R@d~ux~2J-zxr(ZGOjGLC_#mcSsj&?TL~5Z-`SM^kFA{G^JFAGq6=q9 z_?*1h_3V10GtKB!Y?)4LRGQ2TYh;ULM~N_#9X}^Cak457ia3ySz;VVFBLt0$jo65J zg;EYm@FTg2+yV6{>4YF94k|&Rv=g(487FTxDwRev0oF1(ai#`2HmN0tiAG6ufe>{J z_6X%QF>-y$88zJSFc6rjm+W4n^er?BeZ#}rVZ8yUU+VEP9>xn%Ba_7h30{yh?D~;y zqOkEbcC;#KE9EdvixvniZeVhKOp`)^}mmj`iDvVO~^z1 z?#8P-+;GrT5*=v zSDKw&?BcJ#C`^MwJ5+0+l81UZRLfxz1B;1e z^O?=aH{d(zd%?%#_yG9?pWDayd;zB~O$kIakk3s1JXWWU_DOo2oa$zuWMarDq0Jh< z+ouCJoi7QV$^+i<_FGWMZcC}V>xt&ROZzJp9eJm>>ER7?Y%f-P+R(q0_!_(B?)s4% zI_mCiE?9KpqrQEY@1LDr*IVQHVA9$jtlIe0n!Nqni6m1__7hI>M3N`P(u>qELk80^ zus%WO)?uB_YW5@E&0}5}=9T6!BAojdJ@-bBTk2}^6y9XdQ8+~)oJahf_=Ol7y4L={ zvT$zGgR4f__2M7ItKx6PE0085A6>KV=&}%{HZ6&llthJQ$AUbsV%eAqa#Vm+0+As` zr2>si;YZ*m;7T4=D1ZxNDn`mMjEm9em<&-;MhR(&1tgvUP0TC3S?~2OW*q@|eerJm z9=rae_|{4B@#NE)*T~Zq1c?(PM$-(lD$M!m+Dk0QVV0FanD(BYmW^rP}NYe!(O&%gmReSB=w?iLsKaG2h_#Oe8HLySf zMaoJgu3}*_3ta$dX_i#2Pp9+vQK~yNmU=RkO||&la$?_fuCT}B&^t*(3ZHQ}F^b&k za*o~v0pId@{4&p&Fu9HLfM;Bk=y<7zz3_$jhrUlv*3EzTKL+4P?bB1mzcn9gi59gU zSw3`Jd=jgVKeyo6<=s0!Jh52(iSJVB`bUFbX;TDes?L7J@TX!LTW@re{xqy}NuZgS_!|RE=!+dgg z2BpLl3=xBOi5M`_;0@&mNPK{SAwuqrv*w&{VW{3MYn~+4tKs*MJkAY)$gP>cRy) z@h_qUJC2CGM2WwR^F&ut&S`t+P$;HPJe`xX$!5h!g-Et1N>ciKsRa?%F#U1e5H4ib zUymg2!$rt_%;>S$(xWEmHbI>Us!U)q82l__Vi^P5r+P?*H>uzb71XL=CLxVRldy{# zZXXBT#5n3Ib-0U=53_=fW95w5kFixI_tQ15SizWRV2Vs){eVwezvytH16;zlbb$|f z3FGcUbd|nqTTtph7oDN}B0q}I59pN}HH}S;nQTYW0C=?nz#@z!L zR^wibv78Pz#?-rbXyP{#jhbiGlZ;!#!4fspwHU62mV1Y5Ya@g`ePR z_6*Z-{Yk=&Cz%EbbAQEtK(vby1<{IF+1>!`b;CX<^jlz(q1u3J)G$d6(|9Q0p->Jp zFyv$4e8?`?-FC)q4|#oQba>XORJol0hvC_TRr=l-EkW0};A(t)`+s|A!Ga_2Z{PjF zgYy<1eScfsftC5VaMiwriw?FF=dU`*?ppNlZ+7qc&GCix55K$l-cOIuzs{C)oNR9S zVaMcxj%PM5J=!rPX`MWT=2~P&(_+Cb=6lSzN54;xWj<*<`YX z<#L5Ptdf+VLQ;Z~woaJ-u_ETu7FTRYqO>f=D@kl}Jke~if+x`#?qT1&`hkB+S#{12 zhp@BhKscAL#8DUx31bim+Z3*!AwJ&2>8;v#>eGVNPw+Txm9YHIWoM zk(9~k<=Dne#n4p*J&}D8+@0B(N#@PZ7FA& zv{h@&p~-$vZidfj%AV6zSG~19x2XBvT6I}tsVgOWdMG$4J7hJN%w08QMkn!)>UPXe z=96T8CwT{{F@+rbM8C6P8MRfI+A8YlT#AoKkb#b{dYIpdy%)so%ukv3u1A>nPSSha zN4PYH+#?M�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

    XPEtPY{=;VZTp0<&_kN30QHjJ4Rzf&jjtp=c ziyNON-}hPiLBE)Aqny-ilvWkyiy{viPQZVbLRitTll=5F*H|iS8#%Q8!WGiVcPx$K z#3N$)XT&it-o^#`62)BhZI4>6<7SQUmDLjIVhQ6Dqc z!PAeQ`QMIn0Q|~jl~*sy}+DVd*1qk zm4fqjY{)C!ugov4NtYAv^%`GGVqeDbk)*2Vh3dUGmOsh67-qc4F3<>#MF%w& z34>2BjtaBaqn>o_)J&SQvm4P}XvbTSh4*gloJbjZKmGOVn1vUk29xOyduV_T3GSOH zjFMFT+2MzV@4KUQPhQ0Ay~FVS@S=bVkg8N;S7h0ndl*?_SwHG`(5xO-F@*77O0JVG zy41om|1-?bZ>W%|WZNl}EBnaF?Gf2X)Dg9fW?t{x8f{Ufyk0f6LGoS;XI`Hdk{z$r zdu3Bp7#04cy3h{RBR)*i?5Aw6N0#fm+M4oOC(m9ZidHIpJHewRyU0uSlh2t;@a?_e z4-OyErwa;AF0~YuMMzMx7Ve4$igycI4|<(pXgoc4*Q21P#BL&ifB%Mca;C%isf@R8 zsKTgIgUYXsbY%`u&8nX9x)+`nwdT#~P&0xZX~#HgSei@H&dcQ+&ClyyGo8m-4^ffjR_Pez4I=w%74w= z34L)_#h8yuqDM>=C5Ed}>vAoxBBEgBd3~BhW+;Rv^azqk3~n#Cu_wbCawy&NiXsj} z^w~&RYrm7tpE7l2Fq(Jn)pjJ+@^RvMB43FEt`L;#VT{TsgjYJ z8)I%$saV{czhbnhcFb%|Pwk?$%Z77nZOZ*%JLOUR;VZ7Il1nZtQsK{kh773Ovaj^{ zpmsR1+;fn7ZBRR^pu=7A-qSIy9^+fvJZ82fMJZmn(h51xXhz&dG7u_;kpGrS@+3k>AuwN_;f$u%fkI(0F~5=1aZj@MbK{3`D3JhhA|h($HAc+oaDhol zhMXBnMAO!F2JI>BCYsEqPBsA{QxEuQv64QkCknS1k>?^?S&MPAG`CLZcS`Y&#fVOa zu&*(>cw-Xd_$EK|4yv*|b5YpSIhovIVoB`F8@fbtOhl#0l2>p|F2GQsikax-nYE)2 z4*khe21wSj4L%?TSKoxHkW_MBeB$V6*OBh&;;Mxw@pIvhi*J}Nohz8LIj%N#f{1lx z?>b^~_`QO{D@;ZCE6ghx{P5|e!tD|E?&JVg8o_w2ZKCZ$npRs2+>$8SA*2D-ut8XW78H|YKHUFOum{hB*Z zLU&$&>5#iU#SaU5K~nkJF>kZqo##nfe7(8Lw-z7HNuQHDLmup8Zj3muW17qiVviAG z;+Oj!Ig>@kpKW|I81u26l%d&;W1ZFGSKU8-J`zo=b>xcg-U!7dX5RCr$HH!N= zNInvIj+2h~(NPj*a8u`zoQ)=ZPsBCt`~AkzcN9T4upcReFVH@xh)gF-Av!gVdQBu2 zurN-}PO@Dultk21clHkL3=d_4ta%8@ne(>M7<0<&=V`2uPapenq5cvxGlhVxq%viG z@GIG%OH@~=24o|9D|*j-BXMUr5x6XC){EK{+2mBb!KfB=^~R}>%$9ZCMdBx^3j>)Z z)b5C;P^|cOOi1joj~p}hEo_uq722aolOvLqw+@jojeybX@)LzBGSW+zFq}Ex9xahY zHYa;GM*p1=i*Z{KG(EH=pAqnxoUUB>C&LO44OZDx3J{T-91u(qU|NxYrJY9cd|mh{L6 zj~Y#jsjtc99l;QFG*K7*_(;77U&Jq}FOqJFJ_ylnygn}J+=t^7W7EBF*O1yg+N3@? zv!->&q3V=0QBO-@J=@g6n&A%d9;tU4w|cJtj$W3kEl@PjRrcrv;{@@9K#X!f_b_8X zh{2?#DSi#NM(q-@^MGFt!Tl!IR9W`D*n5We9`6m`Uqn30le@*M6h}5~IIXy@u+F!x zPZbsz8dyQ9ZyF~bFaNelJ#;qqj*5edRom5AJAn>2s-LP;sAF=p|@IVAxh_y#((}xK*$2UB+&+gY2yDa#e zJy&cX`LUX4mbctePIr6zJH7V%9R&&bu~K~JROPHCP)>Tn`AN6@F>0RTIlQxHTVp<- z8REUIy&PE;TNNj%RCB)Os<-k%HHl%pA&-Jdlx%Q=oWjGWex}i;4<;`(UkpR4UJ>vV zNYL_oPnGT2UR2`eTC^_lwXywPyPI&XaGLOOVHRPwtCm-6ay4?>a?25 zw#~Mk?N57eG1t9$Y4pq} zb*^dX3N3n_UZFmoQ1#vjgQ0H%P*}}z>$|JNj zR{f$xVpS2UZ2B5!S(TYW@p{FuahAC;KO+U(997uiQRkWwZa@g@TsinOuJ3H^k49*A~GEkrKJ* z5T_PSa-Fl0C{8_*BAEI;H7+#@FLN92Hu1LXO_fWz+vxb+F+lel8ZiVhX z(-{*n-})Be3pQWhbZ=C#4R;LLMGb{igkd}0_IVDrwpaydMv1p!n=0OK7eDdi`cl}z zwY9zWW#RC~n=RL|^#?@s;wk1)=P8sk zlns|#37!k0YOHJ&Xfy*=lrQqH6&}h*C_Ywn45{MGW^az1k7!X0R>I2nm%@&?)?6qZD#5AbX&r;Ja@bhuh9SxK3l zE57*Y!$}GaDl0@iPX@nnb!69G(++FZTDgp;|=2W1O>RiD!0qp%G=tV z5EB(!V%EH$*s!3Yt8Sbson(>}^926bCh?89Tf$0*(>wnX9m|{4&!0YdA)S%toa}to z^ZKo;Tc1-_Q{rA`>u%_5=fkg+x^+$KMU@*D%H^BoFBlcpcz66PrtRji#maI_VQ)FT zA9+||V_G^plc`Usuk~s#+AcvqcGuRfX|O;tzN*V(>a%18diLV<#)i_X&rXG({D$jC z`)b|Vy2DbRP=6#FqVA&Zpq61S4lB54ad7pA?$Ni5x4yIKvvG|?e(L%xRn_X!)5ka$ zTP`r=xxf7?@%_c4s>Vy5CeETu8V^&<=T3kk7cF|J{E#%Gj8}3Ib z-BD7EBIjDNDYLP+*K!ngyq_G@^`X`D!RSuQQgS!zRKl>1p526tv%#IcxeAvr$DXW8 z_1%kgDfxPCX(jiwkOSG$rQOF{pB`jA=<9yoU9T;jQ~7rB?QjkD$H6CKys+eK5bVuF%+@g$fs?&V5S9KVGC7a!oi`ndhCiw{U72L9K+Z2!~X@&7kXc%A>!-1l!y zc)>3~6JF#Wy>Y?M5|><^%x{`mxJs+rn7KN+Ia#_l6mVa1x^3Zl$;rm?*FP+sT)F@J zC1@>)mK6Wn#NTwz{iD=ORRF3rs( z+-=CZOQRdq>pV!qViXy*sb;|LmRnlBJ^w&nopo%0R_phB@adNW%x7b8DSMpDQg*@n8D2;%DCeLuVC<1u}4wFE@C6HKA z7)AmH`=dYdztH|`a zqarVT^QMitge+VUiN~N3q8OxttSAZvM~UKO!GG}biU=$MhQ!MwaDN>0?{j}06hKrQ z-P}za%`ElmY{;k3PNZ0=d$@MR{{~wq6K`Z(HNxI~1+??%AJU|$BMuSNHq7aU;Wn?9Q5A)^~LS@Ck%-JcgqAYGzTG~qZL0tO>E8v=(w;R*PLgyBFE@pl{mh9Q(IfE6NtNCX@Q zr2B6)1u#64fJeVz7zhjjM-c28i2wr$_y%AoGz14Y3E`d*C#nwKr18~j=~ep zMFaI9pgj@|l!kE6XcR<$kvJe5gy+Bkx)9JF3CIj5JR1&&g`5M2hZD*v5(loV2+x5> zpn$dc8|_grBxF4l9HYKK05A*|3d75PX#_l$=@_ksrsM|d_o zP&fz-i6GD!V6lNxL&l+DP#A_#FTq?49&%nh76+jV9tWW*90t*IfB=+p2=)SC5FWvS zq7(8Q4nslk!eMAa9RxTqaKin;fuIu73JwGT3d0k|2N-Y)i2T9fa0DSg0Eo~|g1JZ( zAwPiR651Rv4p?JCy1+5N!GT3U_6!G>7cv(Q#S7Gfke482fXFT!fq>EgfrRc4*k?i+ zf+NsqLS29Z-vglm0^-X+_=5Y*Ts#WGOC$_p|A4(Gj3+U0Bm$x{a3m53kw0K|Av8sz zq4Yyy2<qYC13fQ@Hz0ID0nZQFAJor)5CqCgGze}9=c0cjf52T5+Hs&BXb26^D2V-oqrn#h z2XLYg7?v=$z`)UX!dMvt{}qrE&IOVRSr4cxgr*oIVeAOjgZfYq+QOkYfGdRH#X$T5 z9JqZ5U4G;DK|l`imjFf>Ct~1Opy-5nu}G+W!Tv_BfGR-b1&jF&3o9mIU9ceYCfo}a zL|X!KR5;=f57!X z{3?jJAh8sHLG%~-E9fG`0RkODT>wSo-;9IQuE8Y)5=uW{+#z&EKxGXH(nbj15Lk%4 z2dOhe?vX&C33Us&Ux=I{k-y;wSP+62iG;+Rpy~+GX(SR2sYd{d4arG>=YizYztVjO ze?cw|p*;`{$o_!uhRg-No6t@IFAc?kLP2s^a5P9B3Q7-Rq zM0HRefub~IF37PVdV~fXCd2`@450zI1%!?RsUu`A1`^jH(Ktx124GM*K!YM9;d-DN z2{{KKA9NhBVvxBgh~Gzok_TkZ7&IgnKw_Zv10)7oKL9r;P&vThq4dMTpyR;h7-Y{t zoPPs@(iG(4kaJ+6H6Dw)lvFb)HyQb<1Y>oSm#&fqfeH{(zc*+s$8 z5Z{ObEQjs|TzWzF2d!VBz(WPdo}qWvz_|S8Y{1PB$|UMnl1+#g0Zt5sL3s|u6gn3J ziP3>2f%ryH>4W$b6bKUuWgPXJx;)4}AbJEmBcz@KTqq<@{+0ehXb)lm2wjliLX?mO zz}P|OLhl#AWiRv`K=2{!0Ww4A2d;4-vxqtegG2zT@NIGgl7Yy3!woh zSwiF<1+{A+x`Ofp{Tq7#{5}LP8r*^t?&UXmJn*WJ+yKBJ@h%FDgVG-4@eul9U=TYA zZfqca282>L2>me7`yO!B0i_iN4XI=PDxpBm3vzpiT!Gvk!VmDs2EubJGzSAwJ0vbf z{dxdHNN3;zAbSBK4v|x^J;+|LQ2&7frWiWzH@X1o?GQNtZzdpg#zEs^6b@Qr1n*U# zyae~`5ZMI}A0RXU&oUr1z(L+xVSp+?axlPgNc{@j_(Sq(@Nx!f@9}5|41_Nbod#D4 zkemsWG6?e-aQOkb7Xry8jxZhq0S)9X2Ec$K{arQy47`pafPqMl@I45S3{dqY7zfmY z@Ldadse$~fU2}Iev9Y&srKOgX6xX)7Yw_zt}g= zNsz2z6p^xU1zB+Q1FC4h{*vRbf5;*Ie;;AU{jb0H0)Hp*ucwH=_JqUHQVR$uXe$0c D3yRA+ literal 0 HcmV?d00001 diff --git a/docs/examples/basic/checkpointing_and_restarts.ipynb b/docs/examples/basic/checkpointing_and_restarts.ipynb new file mode 100644 index 0000000..64fe026 --- /dev/null +++ b/docs/examples/basic/checkpointing_and_restarts.ipynb @@ -0,0 +1,180 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "# Checkpointing and Restarts\n", + "If `dump_file` is provided Xopt will save the data and the Xopt configuration in a\n", + "yaml file. This can be used directly to create a new Xopt object." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-05-03T19:55:02.557814300Z", + "start_time": "2024-05-03T19:54:59.954542500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:15.718571Z", + "iopub.status.busy": "2024-09-13T15:54:15.718173Z", + "iopub.status.idle": "2024-09-13T15:54:16.708491Z", + "shell.execute_reply": "2024-09-13T15:54:16.708212Z" + } + }, + "outputs": [], + "source": [ + "# Import the class\n", + "from xopt import Xopt\n", + "\n", + "# Make a proper input file.\n", + "YAML = \"\"\"\n", + "dump_file: dump.yml\n", + "generator:\n", + " name: random\n", + "\n", + "evaluator:\n", + " function: xopt.resources.test_functions.tnk.evaluate_TNK\n", + " function_kwargs:\n", + " a: 999\n", + "\n", + "vocs:\n", + " variables:\n", + " x1: [0, 3.14159]\n", + " x2: [0, 3.14159]\n", + " objectives: {y1: MINIMIZE, y2: MINIMIZE}\n", + " constraints:\n", + " c1: [GREATER_THAN, 0]\n", + " c2: [LESS_THAN, 0.5]\n", + " constants: {a: dummy_constant}\n", + "\n", + "\"\"\"" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Checkpoints\n", + "Since we specified a dump file Xopt will dump the data and all of the options\n", + "required to create a new Xopt object that continues the run." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-05-03T19:55:02.741844900Z", + "start_time": "2024-05-03T19:55:02.558814400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:16.710304Z", + "iopub.status.busy": "2024-09-13T15:54:16.710154Z", + "iopub.status.idle": "2024-09-13T15:54:16.754153Z", + "shell.execute_reply": "2024-09-13T15:54:16.753777Z" + } + }, + "outputs": [], + "source": [ + "# create Xopt object.\n", + "X = Xopt.from_yaml(YAML)\n", + "\n", + "# take 10 steps and view data\n", + "for _ in range(10):\n", + " X.step()\n", + "\n", + "X.data" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Create Xopt object from dump file" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-05-03T19:55:02.813814500Z", + "start_time": "2024-05-03T19:55:02.740817500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:16.775975Z", + "iopub.status.busy": "2024-09-13T15:54:16.775763Z", + "iopub.status.idle": "2024-09-13T15:54:16.785072Z", + "shell.execute_reply": "2024-09-13T15:54:16.784799Z" + } + }, + "outputs": [], + "source": [ + "X2 = Xopt.from_file(\"dump.yml\")\n", + "X2" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-05-03T19:55:02.946844800Z", + "start_time": "2024-05-03T19:55:02.782814900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:16.786507Z", + "iopub.status.busy": "2024-09-13T15:54:16.786330Z", + "iopub.status.idle": "2024-09-13T15:54:16.842388Z", + "shell.execute_reply": "2024-09-13T15:54:16.842111Z" + } + }, + "outputs": [], + "source": [ + "for _ in range(10):\n", + " X2.step()\n", + "\n", + "X2.data" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/basic/dump.yml b/docs/examples/basic/dump.yml new file mode 100644 index 0000000..5259234 --- /dev/null +++ b/docs/examples/basic/dump.yml @@ -0,0 +1,229 @@ +data: + a: + '0': dummy_constant + '1': dummy_constant + '10': dummy_constant + '11': dummy_constant + '12': dummy_constant + '13': dummy_constant + '14': dummy_constant + '15': dummy_constant + '16': dummy_constant + '17': dummy_constant + '18': dummy_constant + '19': dummy_constant + '2': dummy_constant + '3': dummy_constant + '4': dummy_constant + '5': dummy_constant + '6': dummy_constant + '7': dummy_constant + '8': dummy_constant + '9': dummy_constant + c1: + '0': 16.8687531669 + '1': -0.7162468842 + '10': 1.2808872726 + '11': 4.0729849484 + '12': 9.8696135232 + '13': 15.1328894688 + '14': 9.7784036149 + '15': -0.1751019073 + '16': 7.708008318 + '17': 5.6624589991 + '18': 9.8800266769 + '19': 7.7109908429 + '2': 8.8343541105 + '3': 2.5626716002 + '4': 0.628348862 + '5': 5.1854360775 + '6': 2.8638942934 + '7': 4.6390051108 + '8': 9.5898268302 + '9': 7.6409845263 + c2: + '0': 12.4734054036 + '1': 0.2251586888 + '10': 1.1897073502 + '11': 2.8430234481 + '12': 6.9262635811 + '13': 10.9817265145 + '14': 6.6544000963 + '15': 0.3858353762 + '16': 5.0374618482 + '17': 3.7465822315 + '18': 6.7156194909 + '19': 5.7405521063 + '2': 6.4051478253 + '3': 1.7799217633 + '4': 0.5385157033 + '5': 3.2382660295 + '6': 1.9302493449 + '7': 2.8077426537 + '8': 6.9502231 + '9': 4.9810435493 + x1: + '0': 3.0228010413 + '1': 0.5864469085 + '10': 1.5190863306 + '11': 2.1852293654 + '12': 1.5346072388 + '13': 3.0992987863 + '14': 2.0710547261 + '15': 0.936286057 + '16': 1.6332492033 + '17': 1.1422095497 + '18': 2.7042098474 + '19': 0.4859133143 + '2': 0.9795043472 + '3': 1.8263987544 + '4': 1.2151919773 + '5': 1.7985089476 + '6': 1.8891030742 + '7': 2.0017271965 + '8': 3.0444029498 + '9': 1.6456315297 + x2: + '0': 2.9716149194 + '1': 0.0334320834 + '10': 0.1111936201 + '11': 0.4449960536 + '12': 2.919886659 + '13': 2.5555710481 + '14': 2.546017386 + '15': 0.0578576556 + '16': 2.4373198216 + '17': 2.3259652587 + '18': 1.8627466528 + '19': 2.8959035188 + '2': 2.9849996793 + '3': 0.3565144342 + '4': 0.3356341308 + '5': 1.7458493258 + '6': 0.474662398 + '7': 1.2433425059 + '8': 1.1900990717 + '9': 2.4153516511 + xopt_error: + '0': false + '1': false + '10': false + '11': false + '12': false + '13': false + '14': false + '15': false + '16': false + '17': false + '18': false + '19': false + '2': false + '3': false + '4': false + '5': false + '6': false + '7': false + '8': false + '9': false + xopt_runtime: + '0': 3.0451e-05 + '1': 1.97641e-05 + '10': 0.000118121 + '11': 3.28682e-05 + '12': 2.32961e-05 + '13': 2.005e-05 + '14': 1.69589e-05 + '15': 1.8693e-05 + '16': 1.96053e-05 + '17': 2.0769e-05 + '18': 2.06972e-05 + '19': 1.72588e-05 + '2': 2.05259e-05 + '3': 2.30679e-05 + '4': 2.16002e-05 + '5': 2.22092e-05 + '6': 2.01198e-05 + '7': 1.98912e-05 + '8': 1.74772e-05 + '9': 1.52276e-05 + y1: + '0': 3.0228010413 + '1': 0.5864469085 + '10': 1.5190863306 + '11': 2.1852293654 + '12': 1.5346072388 + '13': 3.0992987863 + '14': 2.0710547261 + '15': 0.936286057 + '16': 1.6332492033 + '17': 1.1422095497 + '18': 2.7042098474 + '19': 0.4859133143 + '2': 0.9795043472 + '3': 1.8263987544 + '4': 1.2151919773 + '5': 1.7985089476 + '6': 1.8891030742 + '7': 2.0017271965 + '8': 3.0444029498 + '9': 1.6456315297 + y2: + '0': 2.9716149194 + '1': 0.0334320834 + '10': 0.1111936201 + '11': 0.4449960536 + '12': 2.919886659 + '13': 2.5555710481 + '14': 2.546017386 + '15': 0.0578576556 + '16': 2.4373198216 + '17': 2.3259652587 + '18': 1.8627466528 + '19': 2.8959035188 + '2': 2.9849996793 + '3': 0.3565144342 + '4': 0.3356341308 + '5': 1.7458493258 + '6': 0.474662398 + '7': 1.2433425059 + '8': 1.1900990717 + '9': 2.4153516511 +dump_file: dump.yml +evaluator: + function: xopt.resources.test_functions.tnk.evaluate_TNK + function_kwargs: + a: 999 + raise_probability: 0 + random_sleep: 0 + sleep: 0 + max_workers: 1 + vectorized: false +generator: + name: random + supports_batch_generation: true + supports_multi_objective: true +max_evaluations: null +serialize_inline: false +serialize_torch: false +strict: true +vocs: + constants: + a: dummy_constant + constraints: + c1: + - GREATER_THAN + - 0.0 + c2: + - LESS_THAN + - 0.5 + objectives: + y1: MINIMIZE + y2: MINIMIZE + observables: [] + variables: + x1: + - 0.0 + - 3.14159 + x2: + - 0.0 + - 3.14159 diff --git a/docs/examples/basic/xopt_basic.ipynb b/docs/examples/basic/xopt_basic.ipynb new file mode 100644 index 0000000..de84738 --- /dev/null +++ b/docs/examples/basic/xopt_basic.ipynb @@ -0,0 +1,636 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Xopt basic example\n", + "\n", + "Xopt optimization problems can be defined via one of two methods:\n", + "- a yaml text file (for limiting the amount of python script writing and/or setting up simulation runs)\n", + "- a simple python script (for those who prefer to use python directly)\n", + "\n", + "Here we will demonstrate how both of these techniques can be used to solve a relatively simple constrained optimization problem.\n", + "\n", + "$n=2$ variables:\n", + "$x_i \\in [0, \\pi], i=1,2$\n", + "\n", + "Objective:\n", + "- $f(x) = \\sum_i x_i$\n", + "\n", + "Constraint:\n", + "- $g(x) = -x_1^2 -x_2^2 + 1 \\le 0$" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Xopt Components\n", + "The definition of the Xopt object requires 3 parts, listed below:\n", + "- The `Evaluator` object, which evaluates input points using the arbitrary function\n", + "specified by the `function` property.\n", + "- The `Generator` object, which, when given data that has been evaluated, generates\n", + "future points to evaluate using the evaluator.\n", + "- The `VOCS` (variables, objectives, constraints, statics) object, which specifies the\n", + "input domain, the objectives, constraints and constants passed to the evaluator\n", + "function.\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Import " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:54:36.148851Z", + "iopub.status.busy": "2024-09-13T15:54:36.148739Z", + "iopub.status.idle": "2024-09-13T15:54:37.136112Z", + "shell.execute_reply": "2024-09-13T15:54:37.135806Z" + } + }, + "outputs": [], + "source": [ + "from xopt import Evaluator\n", + "from xopt import VOCS\n", + "from xopt import Xopt\n", + "from xopt.generators import list_available_generators\n", + "from xopt.generators import get_generator\n", + "import math" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Defining Xopt components using python\n", + "We first examine how one would create and configure and Xopt optimization run using\n", + "python. This can also be done via a YAML file (see the next section)." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "### Define the objective function and the evaluator\n", + "Note that the objective function takes in a dict of variable values and returns a dict of objective return values. The keys of the input and output dictionaries must contain the keys we will specify in VOCS (see below)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-03-13T01:32:42.498257800Z", + "start_time": "2024-03-13T01:32:40.155677200Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:37.138011Z", + "iopub.status.busy": "2024-09-13T15:54:37.137879Z", + "iopub.status.idle": "2024-09-13T15:54:37.142258Z", + "shell.execute_reply": "2024-09-13T15:54:37.142023Z" + } + }, + "outputs": [], + "source": [ + "def evaluate_function(inputs: dict) -> dict:\n", + " objective_value = inputs[\"x1\"] ** 2 + inputs[\"x2\"] ** 2\n", + " constraint_value = -(inputs[\"x1\"] ** 2) - inputs[\"x2\"] ** 2 + 1\n", + " return {\"f\": objective_value, \"g\": constraint_value}\n", + "\n", + "\n", + "evaluator = Evaluator(function=evaluate_function)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "### Define VOCS\n", + "Here we define the names and ranges of input parameters, the names and settings of\n", + "objectives, and the names and settings of constraints. Note that the keys here should\n", + " be referenced in the evaluate function above." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-03-13T01:32:42.513257500Z", + "start_time": "2024-03-13T01:32:42.502259Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:37.143615Z", + "iopub.status.busy": "2024-09-13T15:54:37.143539Z", + "iopub.status.idle": "2024-09-13T15:54:37.145367Z", + "shell.execute_reply": "2024-09-13T15:54:37.145161Z" + } + }, + "outputs": [], + "source": [ + "vocs = VOCS(\n", + " variables={\"x1\": [0, math.pi], \"x2\": [0, math.pi]},\n", + " objectives={\"f\": \"MINIMIZE\"},\n", + " constraints={\"g\": [\"LESS_THAN\", 0]},\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "### Define the Generator\n", + "First lets see which generators are available for use." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-03-13T01:32:43.608257600Z", + "start_time": "2024-03-13T01:32:42.515259Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:37.147015Z", + "iopub.status.busy": "2024-09-13T15:54:37.146935Z", + "iopub.status.idle": "2024-09-13T15:54:37.755022Z", + "shell.execute_reply": "2024-09-13T15:54:37.754727Z" + } + }, + "outputs": [], + "source": [ + "list_available_generators()" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "Here we will use the simplest generator that is defined by Xopt, random number generation." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-03-13T01:32:43.652266600Z", + "start_time": "2024-03-13T01:32:43.611259600Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:37.777252Z", + "iopub.status.busy": "2024-09-13T15:54:37.777024Z", + "iopub.status.idle": "2024-09-13T15:54:37.779234Z", + "shell.execute_reply": "2024-09-13T15:54:37.778989Z" + } + }, + "outputs": [], + "source": [ + "# get the docstring for the random generator\n", + "print(get_generator(\"random\").__doc__)\n", + "\n", + "# use the get generator method to get the random number generator\n", + "generator = get_generator(\"random\")(vocs=vocs)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "### Combine into Xopt object" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-03-13T01:32:43.652266600Z", + "start_time": "2024-03-13T01:32:43.626258200Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:37.780722Z", + "iopub.status.busy": "2024-09-13T15:54:37.780612Z", + "iopub.status.idle": "2024-09-13T15:54:37.782226Z", + "shell.execute_reply": "2024-09-13T15:54:37.781968Z" + } + }, + "outputs": [], + "source": [ + "X = Xopt(vocs=vocs, generator=generator, evaluator=evaluator)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Defining Xopt object from yaml file\n", + "Alternatively, it might be more useful to define the Xopt object from a text file or\n", + "YAML string. We replicate the code above with the YAML file below." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-03-13T01:32:43.660292300Z", + "start_time": "2024-03-13T01:32:43.641259200Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:37.783675Z", + "iopub.status.busy": "2024-09-13T15:54:37.783585Z", + "iopub.status.idle": "2024-09-13T15:54:37.785281Z", + "shell.execute_reply": "2024-09-13T15:54:37.785057Z" + } + }, + "outputs": [], + "source": [ + "# Make a proper input file.\n", + "YAML = \"\"\"\n", + "evaluator:\n", + " function: __main__.evaluate_function\n", + "\n", + "generator:\n", + " name: random\n", + "\n", + "vocs:\n", + " variables:\n", + " x1: [0, 3.14159]\n", + " x2: [0, 3.14159]\n", + " objectives: {f: MINIMIZE}\n", + " constraints:\n", + " g: [LESS_THAN, 0]\n", + "\n", + "\"\"\"" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-03-13T01:32:43.669259800Z", + "start_time": "2024-03-13T01:32:43.655257700Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:37.786740Z", + "iopub.status.busy": "2024-09-13T15:54:37.786655Z", + "iopub.status.idle": "2024-09-13T15:54:37.789636Z", + "shell.execute_reply": "2024-09-13T15:54:37.789373Z" + } + }, + "outputs": [], + "source": [ + "# create Xopt object.\n", + "X_from_yaml = Xopt.from_yaml(YAML)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Introspection\n", + "Objects in Xopt can be printed to a string or dumped to a text file for easy\n", + "introspection of attributes and current configuration." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-03-13T01:32:43.712296Z", + "start_time": "2024-03-13T01:32:43.671257800Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:37.791038Z", + "iopub.status.busy": "2024-09-13T15:54:37.790938Z", + "iopub.status.idle": "2024-09-13T15:54:37.794335Z", + "shell.execute_reply": "2024-09-13T15:54:37.794092Z" + } + }, + "outputs": [], + "source": [ + "# Convenient representation of the state.\n", + "X" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Evaluating randomly generated or fixed inputs.\n", + "The main Xopt object has a variety of means for evaluating random or fixed points.\n", + "This is often used to initialize optimization, but can be used independently of any\n", + "generator. Results from evaluations are stored in the `data` attribute. Data can also\n", + " be explictly added to the Xopt object (and by extension the generator attached to\n", + " the xopt object by calling `X.add_data()`." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-03-13T01:32:43.722288700Z", + "start_time": "2024-03-13T01:32:43.687283700Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:37.795665Z", + "iopub.status.busy": "2024-09-13T15:54:37.795566Z", + "iopub.status.idle": "2024-09-13T15:54:37.802776Z", + "shell.execute_reply": "2024-09-13T15:54:37.802553Z" + } + }, + "outputs": [], + "source": [ + "# randomly evaluate some points and add data to Xopt object\n", + "X.random_evaluate(5)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-03-13T01:32:43.722288700Z", + "start_time": "2024-03-13T01:32:43.712296Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:37.804109Z", + "iopub.status.busy": "2024-09-13T15:54:37.804027Z", + "iopub.status.idle": "2024-09-13T15:54:37.808684Z", + "shell.execute_reply": "2024-09-13T15:54:37.808446Z" + } + }, + "outputs": [], + "source": [ + "# evaluate some points additionally\n", + "points = {\"x1\": [1.0, 0.5, 2.25], \"x2\": [0, 1.75, 0.6]}\n", + "X.evaluate_data(points)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-03-13T01:32:43.729258500Z", + "start_time": "2024-03-13T01:32:43.716261900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:37.810013Z", + "iopub.status.busy": "2024-09-13T15:54:37.809931Z", + "iopub.status.idle": "2024-09-13T15:54:37.813719Z", + "shell.execute_reply": "2024-09-13T15:54:37.813492Z" + } + }, + "outputs": [], + "source": [ + "# examine the data stored in Xopt\n", + "X.data" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Optimization\n", + "Xopt conducts a single iteration of optimization by calling `X.step()`. Inside this\n", + "function Xopt will generate a point (or set of points) using the generator object,\n", + "then send the point to be evaluated by the evaluator. Results will be stored in the\n", + "data attribute." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-03-13T01:32:43.772322900Z", + "start_time": "2024-03-13T01:32:43.730259200Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:37.815111Z", + "iopub.status.busy": "2024-09-13T15:54:37.815038Z", + "iopub.status.idle": "2024-09-13T15:54:37.817763Z", + "shell.execute_reply": "2024-09-13T15:54:37.817558Z" + } + }, + "outputs": [], + "source": [ + "# Take one step (generate a single point)\n", + "X.step()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-03-13T01:32:43.862089800Z", + "start_time": "2024-03-13T01:32:43.745260300Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:37.818983Z", + "iopub.status.busy": "2024-09-13T15:54:37.818903Z", + "iopub.status.idle": "2024-09-13T15:54:37.822785Z", + "shell.execute_reply": "2024-09-13T15:54:37.822555Z" + } + }, + "outputs": [], + "source": [ + "# examine the results\n", + "X.data" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-03-13T01:32:43.897089900Z", + "start_time": "2024-03-13T01:32:43.772322900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:37.824518Z", + "iopub.status.busy": "2024-09-13T15:54:37.824357Z", + "iopub.status.idle": "2024-09-13T15:54:37.839928Z", + "shell.execute_reply": "2024-09-13T15:54:37.839600Z" + } + }, + "outputs": [], + "source": [ + "# take a couple of steps and examine the results\n", + "for _ in range(10):\n", + " X.step()\n", + "X.data" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Find and evaluate the best point from `X.data`" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-03-13T01:32:43.937089900Z", + "start_time": "2024-03-13T01:32:43.832332500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:37.841842Z", + "iopub.status.busy": "2024-09-13T15:54:37.841699Z", + "iopub.status.idle": "2024-09-13T15:54:37.849613Z", + "shell.execute_reply": "2024-09-13T15:54:37.849371Z" + } + }, + "outputs": [], + "source": [ + "idx, val, params = X.vocs.select_best(X.data)\n", + "print(f\"best objective value {val}\")\n", + "print(f\"best point {params}\")\n", + "\n", + "X.evaluate_data(params)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Visualization\n", + "Finally, we can visualize the objectives and variables to monitor optimization or\n", + "visualize the results" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-03-13T01:32:44.620735900Z", + "start_time": "2024-03-13T01:32:43.851332300Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:37.851221Z", + "iopub.status.busy": "2024-09-13T15:54:37.851110Z", + "iopub.status.idle": "2024-09-13T15:54:38.258640Z", + "shell.execute_reply": "2024-09-13T15:54:38.258327Z" + } + }, + "outputs": [], + "source": [ + "# view objective values\n", + "X.data.plot(y=X.vocs.objective_names)\n", + "\n", + "# view variables values\n", + "X.data.plot(*X.vocs.variable_names, kind=\"scatter\")\n", + "\n", + "# you can also normalize the variables\n", + "X.vocs.normalize_inputs(X.data).plot(*X.vocs.variable_names, kind=\"scatter\")" + ] + } + ], + "metadata": { + "interpreter": { + "hash": "72034539424920dfb606fe3b820b3f27dca0cbf1c69938110810ec4641e275b1" + }, + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/basic/xopt_evaluator.ipynb b/docs/examples/basic/xopt_evaluator.ipynb new file mode 100644 index 0000000..95ec2a2 --- /dev/null +++ b/docs/examples/basic/xopt_evaluator.ipynb @@ -0,0 +1,576 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Xopt Evaluator Basic Usage \n", + "\n", + "The `Evaluator` handles the execution of the user-provided `function` with optional `function_kwags`, asyncrhonously and parallel, with exception handling. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-08T21:35:16.928260600Z", + "start_time": "2023-09-08T21:35:16.919590900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:26.524566Z", + "iopub.status.busy": "2024-09-13T15:54:26.524282Z", + "iopub.status.idle": "2024-09-13T15:54:27.553451Z", + "shell.execute_reply": "2024-09-13T15:54:27.553023Z" + } + }, + "outputs": [], + "source": [ + "from xopt import Xopt, Evaluator, VOCS\n", + "from xopt.generators.random import RandomGenerator\n", + "\n", + "# Usage with a parallel executor.\n", + "from xopt import AsynchronousXopt\n", + "\n", + "import pandas as pd\n", + "\n", + "from time import sleep\n", + "from numpy.random import randint\n", + "\n", + "from typing import Dict\n", + "\n", + "import numpy as np\n", + "\n", + "from concurrent.futures import ProcessPoolExecutor\n", + "\n", + "# needed for macos\n", + "import platform\n", + "\n", + "if platform.system() == \"Darwin\":\n", + " import multiprocessing\n", + "\n", + " multiprocessing.set_start_method(\"fork\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-08T21:35:32.309828Z", + "start_time": "2023-09-08T21:35:16.928260600Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:27.555306Z", + "iopub.status.busy": "2024-09-13T15:54:27.555168Z", + "iopub.status.idle": "2024-09-13T15:54:27.556849Z", + "shell.execute_reply": "2024-09-13T15:54:27.556651Z" + } + }, + "outputs": [], + "source": [ + "np.random.seed(666) # for reproducibility" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Define a custom function `f(inputs: Dict) -> outputs: Dict`. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-08T21:35:32.324561500Z", + "start_time": "2023-09-08T21:35:32.311827800Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:27.558136Z", + "iopub.status.busy": "2024-09-13T15:54:27.558062Z", + "iopub.status.idle": "2024-09-13T15:54:27.560087Z", + "shell.execute_reply": "2024-09-13T15:54:27.559863Z" + } + }, + "outputs": [], + "source": [ + "def f(inputs: Dict, enable_errors=True) -> Dict:\n", + " sleep(randint(1, 5) * 0.1) # simulate computation time\n", + " # Make some occasional errors\n", + " if enable_errors and np.any(inputs[\"x\"] > 0.8):\n", + " raise ValueError(\"x > 0.8\")\n", + "\n", + " return {\"f1\": inputs[\"x\"] ** 2 + inputs[\"y\"] ** 2}" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Define variables, objectives, constraints, and other settings (VOCS)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-08T21:35:32.368050300Z", + "start_time": "2023-09-08T21:35:32.328590900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:27.561752Z", + "iopub.status.busy": "2024-09-13T15:54:27.561657Z", + "iopub.status.idle": "2024-09-13T15:54:27.564957Z", + "shell.execute_reply": "2024-09-13T15:54:27.564762Z" + } + }, + "outputs": [], + "source": [ + "vocs = VOCS(variables={\"x\": [0, 1], \"y\": [0, 1]}, objectives={\"f1\": \"MINIMIZE\"})\n", + "vocs" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "This can be used to make some random inputs for evaluating the function. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-08T21:35:32.676437500Z", + "start_time": "2023-09-08T21:35:32.340456300Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:27.586881Z", + "iopub.status.busy": "2024-09-13T15:54:27.586726Z", + "iopub.status.idle": "2024-09-13T15:54:27.893588Z", + "shell.execute_reply": "2024-09-13T15:54:27.893264Z" + } + }, + "outputs": [], + "source": [ + "in1 = vocs.random_inputs()[0]\n", + "\n", + "f(in1, enable_errors=False)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-08T21:35:33.005111700Z", + "start_time": "2023-09-08T21:35:32.681546900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:27.895291Z", + "iopub.status.busy": "2024-09-13T15:54:27.895153Z", + "iopub.status.idle": "2024-09-13T15:54:28.206981Z", + "shell.execute_reply": "2024-09-13T15:54:28.206227Z" + } + }, + "outputs": [], + "source": [ + "# Add in occasional errors.\n", + "try:\n", + " f({\"x\": 1, \"y\": 0})\n", + "except Exception as ex:\n", + " print(f\"Caught error in f: {ex}\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-08T21:35:33.049056200Z", + "start_time": "2023-09-08T21:35:33.006111Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:28.211066Z", + "iopub.status.busy": "2024-09-13T15:54:28.210530Z", + "iopub.status.idle": "2024-09-13T15:54:28.220673Z", + "shell.execute_reply": "2024-09-13T15:54:28.220185Z" + } + }, + "outputs": [], + "source": [ + "# Create Evaluator\n", + "ev = Evaluator(function=f)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-08T21:35:33.252318Z", + "start_time": "2023-09-08T21:35:33.021667400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:28.223163Z", + "iopub.status.busy": "2024-09-13T15:54:28.222977Z", + "iopub.status.idle": "2024-09-13T15:54:28.435669Z", + "shell.execute_reply": "2024-09-13T15:54:28.435086Z" + } + }, + "outputs": [], + "source": [ + "# Single input evaluation\n", + "ev.evaluate(in1)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-08T21:35:35.961577400Z", + "start_time": "2023-09-08T21:35:33.250319900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:28.438836Z", + "iopub.status.busy": "2024-09-13T15:54:28.438558Z", + "iopub.status.idle": "2024-09-13T15:54:31.093684Z", + "shell.execute_reply": "2024-09-13T15:54:31.093111Z" + } + }, + "outputs": [], + "source": [ + "# Dataframe evaluation\n", + "in10 = pd.DataFrame({\"x\": np.linspace(0, 1, 10), \"y\": np.linspace(0, 1, 10)})\n", + "ev.evaluate_data(in10)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-08T21:35:36.188682500Z", + "start_time": "2023-09-08T21:35:35.964575800Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:31.097149Z", + "iopub.status.busy": "2024-09-13T15:54:31.096920Z", + "iopub.status.idle": "2024-09-13T15:54:31.311399Z", + "shell.execute_reply": "2024-09-13T15:54:31.310884Z" + } + }, + "outputs": [], + "source": [ + "# Dataframe evaluation, vectorized\n", + "ev.vectorized = True\n", + "ev.evaluate_data(in10)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Executors" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-08T21:35:36.210825800Z", + "start_time": "2023-09-08T21:35:36.189682300Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:31.314542Z", + "iopub.status.busy": "2024-09-13T15:54:31.314152Z", + "iopub.status.idle": "2024-09-13T15:54:31.316966Z", + "shell.execute_reply": "2024-09-13T15:54:31.316499Z" + } + }, + "outputs": [], + "source": [ + "MAX_WORKERS = 10" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-08T21:35:36.277827Z", + "start_time": "2023-09-08T21:35:36.205828Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:31.319258Z", + "iopub.status.busy": "2024-09-13T15:54:31.319060Z", + "iopub.status.idle": "2024-09-13T15:54:31.323973Z", + "shell.execute_reply": "2024-09-13T15:54:31.323589Z" + } + }, + "outputs": [], + "source": [ + "# Create Executor instance\n", + "executor = ProcessPoolExecutor(max_workers=MAX_WORKERS)\n", + "executor" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-08T21:35:36.336827600Z", + "start_time": "2023-09-08T21:35:36.219826200Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:31.326164Z", + "iopub.status.busy": "2024-09-13T15:54:31.326004Z", + "iopub.status.idle": "2024-09-13T15:54:31.327802Z", + "shell.execute_reply": "2024-09-13T15:54:31.327526Z" + } + }, + "outputs": [], + "source": [ + "# Dask (Optional)\n", + "# from dask.distributed import Client\n", + "# import logging\n", + "# client = Client( silence_logs=logging.ERROR)\n", + "# executor = client.get_executor()\n", + "# client" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-08T21:35:36.340830Z", + "start_time": "2023-09-08T21:35:36.246825700Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:31.329751Z", + "iopub.status.busy": "2024-09-13T15:54:31.329593Z", + "iopub.status.idle": "2024-09-13T15:54:31.336762Z", + "shell.execute_reply": "2024-09-13T15:54:31.336461Z" + } + }, + "outputs": [], + "source": [ + "# This calls `executor.map`\n", + "ev = Evaluator(function=f, executor=executor, max_workers=MAX_WORKERS)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-08T21:35:42.832826300Z", + "start_time": "2023-09-08T21:35:36.250828900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:31.338377Z", + "iopub.status.busy": "2024-09-13T15:54:31.338268Z", + "iopub.status.idle": "2024-09-13T15:54:31.794548Z", + "shell.execute_reply": "2024-09-13T15:54:31.793918Z" + } + }, + "outputs": [], + "source": [ + "# This will run in parallel\n", + "ev.evaluate_data(in10)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Evaluator in the Xopt object" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-08T21:35:49.453947100Z", + "start_time": "2023-09-08T21:35:48.973424600Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:31.797478Z", + "iopub.status.busy": "2024-09-13T15:54:31.797291Z", + "iopub.status.idle": "2024-09-13T15:54:32.225792Z", + "shell.execute_reply": "2024-09-13T15:54:32.225518Z" + } + }, + "outputs": [], + "source": [ + "X = Xopt(\n", + " generator=RandomGenerator(vocs=vocs), evaluator=Evaluator(function=f), vocs=vocs\n", + ")\n", + "X.strict = False\n", + "\n", + "# Evaluate to the evaluator some new inputs\n", + "X.evaluate_data(X.vocs.random_inputs(4))" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Asynchronous Xopt\n", + "Instead of waiting for evaluations to be finished, AsynchronousXopt can be used to generate candidates while waiting for other evaluations to finish (requires parallel execution). In this case, calling ```X.step()``` generates and executes a number of candidates that are executed in parallel using python ```concurrent.futures``` formalism. Calling ```X.step()``` again will generate and evaluate new points based on finished futures asynchronously." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-08T21:35:50.776098900Z", + "start_time": "2023-09-08T21:35:50.753057600Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:32.227332Z", + "iopub.status.busy": "2024-09-13T15:54:32.227223Z", + "iopub.status.idle": "2024-09-13T15:54:32.231134Z", + "shell.execute_reply": "2024-09-13T15:54:32.230814Z" + } + }, + "outputs": [], + "source": [ + "executor = ProcessPoolExecutor(max_workers=MAX_WORKERS)\n", + "\n", + "X2 = AsynchronousXopt(\n", + " generator=RandomGenerator(vocs=vocs),\n", + " evaluator=Evaluator(function=f, executor=executor, max_workers=MAX_WORKERS),\n", + " vocs=vocs,\n", + ")\n", + "X2.strict = False" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-08T21:35:57.154830200Z", + "start_time": "2023-09-08T21:35:51.660788Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:32.232629Z", + "iopub.status.busy": "2024-09-13T15:54:32.232540Z", + "iopub.status.idle": "2024-09-13T15:54:32.477829Z", + "shell.execute_reply": "2024-09-13T15:54:32.477089Z" + } + }, + "outputs": [], + "source": [ + "X2.step()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:54:32.480558Z", + "iopub.status.busy": "2024-09-13T15:54:32.480378Z", + "iopub.status.idle": "2024-09-13T15:54:33.023925Z", + "shell.execute_reply": "2024-09-13T15:54:33.023594Z" + } + }, + "outputs": [], + "source": [ + "for _ in range(20):\n", + " X2.step()\n", + "\n", + "len(X2.data)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:54:33.025554Z", + "iopub.status.busy": "2024-09-13T15:54:33.025427Z", + "iopub.status.idle": "2024-09-13T15:54:33.353435Z", + "shell.execute_reply": "2024-09-13T15:54:33.353146Z" + } + }, + "outputs": [], + "source": [ + "X2.data.plot.scatter(\"x\", \"y\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:54:33.355036Z", + "iopub.status.busy": "2024-09-13T15:54:33.354876Z", + "iopub.status.idle": "2024-09-13T15:54:33.977523Z", + "shell.execute_reply": "2024-09-13T15:54:33.976871Z" + }, + "tags": [] + }, + "outputs": [], + "source": [ + "# Asynchronous, Vectorized\n", + "X2 = AsynchronousXopt(\n", + " generator=RandomGenerator(vocs=vocs),\n", + " evaluator=Evaluator(function=f, executor=executor, max_workers=MAX_WORKERS),\n", + " vocs=vocs,\n", + ")\n", + "X2.evaluator.vectorized = True\n", + "X2.strict = False\n", + "\n", + "# This takes fewer steps to achieve a similar number of evaluations\n", + "for _ in range(3):\n", + " X2.step()\n", + "\n", + "len(X2.data)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + }, + "vscode": { + "interpreter": { + "hash": "4483d4964800812ebc77892a92dde3b54705ec8a224d63d9bb659e2cc457018b" + } + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/basic/xopt_generator.ipynb b/docs/examples/basic/xopt_generator.ipynb new file mode 100644 index 0000000..676104b --- /dev/null +++ b/docs/examples/basic/xopt_generator.ipynb @@ -0,0 +1,285 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Working with Xopt generators\n", + "\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-04-02T14:38:03.984509500Z", + "start_time": "2024-04-02T14:37:58.291483Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:18.892761Z", + "iopub.status.busy": "2024-09-13T15:54:18.892631Z", + "iopub.status.idle": "2024-09-13T15:54:19.917312Z", + "shell.execute_reply": "2024-09-13T15:54:19.916980Z" + } + }, + "outputs": [], + "source": [ + "# Import the class\n", + "from xopt.generators import generators, get_generator\n", + "from xopt.vocs import VOCS\n", + "from xopt import Xopt, Evaluator, Generator\n", + "\n", + "import math\n", + "import numpy as np" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-04-02T14:38:04.059481Z", + "start_time": "2024-04-02T14:38:04.043479100Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:19.919265Z", + "iopub.status.busy": "2024-09-13T15:54:19.919104Z", + "iopub.status.idle": "2024-09-13T15:54:19.922532Z", + "shell.execute_reply": "2024-09-13T15:54:19.922173Z" + } + }, + "outputs": [], + "source": [ + "# named generators\n", + "generators.keys()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-04-02T14:38:06.698513600Z", + "start_time": "2024-04-02T14:38:04.061480600Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:19.944610Z", + "iopub.status.busy": "2024-09-13T15:54:19.944468Z", + "iopub.status.idle": "2024-09-13T15:54:20.524671Z", + "shell.execute_reply": "2024-09-13T15:54:20.524249Z" + } + }, + "outputs": [], + "source": [ + "# get default options for the upper confidence bound generator\n", + "generator_type = get_generator(\"upper_confidence_bound\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-04-02T14:38:06.713510Z", + "start_time": "2024-04-02T14:38:06.701481300Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:20.526871Z", + "iopub.status.busy": "2024-09-13T15:54:20.526495Z", + "iopub.status.idle": "2024-09-13T15:54:20.528754Z", + "shell.execute_reply": "2024-09-13T15:54:20.528499Z" + } + }, + "outputs": [], + "source": [ + "# define vocs for the problem\n", + "\n", + "vocs = VOCS(\n", + " variables={\"x\": [0, 2 * math.pi]},\n", + " objectives={\"f\": \"MINIMIZE\"},\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-04-02T14:38:06.732510500Z", + "start_time": "2024-04-02T14:38:06.716506100Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:20.530460Z", + "iopub.status.busy": "2024-09-13T15:54:20.530338Z", + "iopub.status.idle": "2024-09-13T15:54:20.532404Z", + "shell.execute_reply": "2024-09-13T15:54:20.532136Z" + } + }, + "outputs": [], + "source": [ + "# define a test function to optimize\n", + "\n", + "\n", + "def test_function(input_dict):\n", + " return {\"f\": np.sin(input_dict[\"x\"])}" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-04-02T14:38:06.787509400Z", + "start_time": "2024-04-02T14:38:06.730483400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:20.533901Z", + "iopub.status.busy": "2024-09-13T15:54:20.533785Z", + "iopub.status.idle": "2024-09-13T15:54:20.593852Z", + "shell.execute_reply": "2024-09-13T15:54:20.593555Z" + } + }, + "outputs": [], + "source": [ + "evaluator = Evaluator(function=test_function)\n", + "generator = generator_type(vocs=vocs)\n", + "X = Xopt(generator=generator, evaluator=evaluator, vocs=vocs)\n", + "X" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-04-02T14:38:07.329478900Z", + "start_time": "2024-04-02T14:38:06.760517Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:20.595302Z", + "iopub.status.busy": "2024-09-13T15:54:20.595189Z", + "iopub.status.idle": "2024-09-13T15:54:21.114663Z", + "shell.execute_reply": "2024-09-13T15:54:21.114313Z" + } + }, + "outputs": [], + "source": [ + "# run the optimization for a couple of iterations (see bayes_opt folder for\n", + "# more examples of ucb)\n", + "X.random_evaluate(2)\n", + "for i in range(4):\n", + " X.step()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-04-02T14:38:07.343479300Z", + "start_time": "2024-04-02T14:38:07.330479700Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:21.116528Z", + "iopub.status.busy": "2024-09-13T15:54:21.116363Z", + "iopub.status.idle": "2024-09-13T15:54:21.121624Z", + "shell.execute_reply": "2024-09-13T15:54:21.121332Z" + } + }, + "outputs": [], + "source": [ + "X.data" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Write your own generator\n", + "Here we write a generator that generates the same point every time." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-04-02T14:38:30.157799200Z", + "start_time": "2024-04-02T14:38:30.148798400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:21.123537Z", + "iopub.status.busy": "2024-09-13T15:54:21.123381Z", + "iopub.status.idle": "2024-09-13T15:54:21.130807Z", + "shell.execute_reply": "2024-09-13T15:54:21.130499Z" + } + }, + "outputs": [], + "source": [ + "class MyGenerator(Generator):\n", + " def generate(self, n_candidates) -> list[dict]:\n", + " points = [{\"x\": 1.0}] * n_candidates\n", + " return points\n", + "\n", + "\n", + "my_generator = MyGenerator(vocs=vocs)\n", + "X2 = Xopt(evaluator=evaluator, vocs=vocs, generator=my_generator)\n", + "\n", + "for i in range(4):\n", + " X2.step()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-04-02T14:38:31.306804300Z", + "start_time": "2024-04-02T14:38:31.288798900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:21.132352Z", + "iopub.status.busy": "2024-09-13T15:54:21.132250Z", + "iopub.status.idle": "2024-09-13T15:54:21.135795Z", + "shell.execute_reply": "2024-09-13T15:54:21.135566Z" + } + }, + "outputs": [], + "source": [ + "X2.data" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + }, + "vscode": { + "interpreter": { + "hash": "e3625c9a0de9d330a79359c7c8508d3b9f835fd7259469d66057de346104c5ec" + } + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/basic/xopt_parallel.ipynb b/docs/examples/basic/xopt_parallel.ipynb new file mode 100644 index 0000000..df0de3f --- /dev/null +++ b/docs/examples/basic/xopt_parallel.ipynb @@ -0,0 +1,596 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "pycharm": { + "name": "#%% md\n" + } + }, + "source": [ + "# Xopt Parallel Examples\n", + "\n", + "Xopt provides methods to parallelize optimizations using Processes, Threads, MPI, and Dask using the `concurrent.futures` interface as defined in https://www.python.org/dev/peps/pep-3148/ ." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:51:11.807711Z", + "iopub.status.busy": "2024-09-13T15:51:11.807234Z", + "iopub.status.idle": "2024-09-13T15:51:12.733177Z", + "shell.execute_reply": "2024-09-13T15:51:12.732871Z" + } + }, + "outputs": [], + "source": [ + "from xopt import AsynchronousXopt as Xopt" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:51:12.734939Z", + "iopub.status.busy": "2024-09-13T15:51:12.734819Z", + "iopub.status.idle": "2024-09-13T15:51:13.118957Z", + "shell.execute_reply": "2024-09-13T15:51:13.118649Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "# Helpers for this notebook\n", + "import multiprocessing\n", + "from concurrent.futures import ProcessPoolExecutor\n", + "from dask.distributed import Client\n", + "\n", + "import matplotlib.pyplot as plt\n", + "\n", + "import pandas as pd\n", + "from concurrent.futures import ThreadPoolExecutor\n", + "\n", + "import os\n", + "\n", + "\n", + "# Notebook printing output\n", + "# from xopt import output_notebook\n", + "# output_notebook()\n", + "\n", + "N_CPUS = multiprocessing.cpu_count()\n", + "N_CPUS\n", + "\n", + "# directory for data.\n", + "os.makedirs(\"temp\", exist_ok=True)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "pycharm": { + "name": "#%% md\n" + } + }, + "source": [ + "The `Xopt` object can be instantiated from a JSON or YAML file, or a dict, with the proper structure.\n", + "\n", + "Here we will make one" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:51:13.120880Z", + "iopub.status.busy": "2024-09-13T15:51:13.120673Z", + "iopub.status.idle": "2024-09-13T15:51:13.139851Z", + "shell.execute_reply": "2024-09-13T15:51:13.139601Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "# Make a proper input file.\n", + "YAML = \"\"\"\n", + "\n", + "max_evaluations: 1000\n", + "\n", + "generator:\n", + " name: cnsga\n", + " output_path: temp\n", + " population_size: 64\n", + " \n", + "evaluator:\n", + " function: xopt.resources.test_functions.tnk.evaluate_TNK\n", + " function_kwargs:\n", + " sleep: 0\n", + " random_sleep: 0.1\n", + " \n", + "vocs:\n", + " variables:\n", + " x1: [0, 3.14159]\n", + " x2: [0, 3.14159]\n", + " objectives: {y1: MINIMIZE, y2: MINIMIZE}\n", + " constraints:\n", + " c1: [GREATER_THAN, 0]\n", + " c2: [LESS_THAN, 0.5]\n", + " constants: {a: dummy_constant}\n", + "\n", + "\"\"\"\n", + "X = Xopt(YAML)\n", + "X" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:51:13.160584Z", + "iopub.status.busy": "2024-09-13T15:51:13.160437Z", + "iopub.status.idle": "2024-09-13T15:51:21.136857Z", + "shell.execute_reply": "2024-09-13T15:51:21.135973Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "%%timeit\n", + "# Check that the average time is close to random_sleep\n", + "X.evaluator.function({\"x1\": 0.5, \"x2\": 0.5}, random_sleep=0.1)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:51:21.140796Z", + "iopub.status.busy": "2024-09-13T15:51:21.140489Z", + "iopub.status.idle": "2024-09-13T15:53:14.801654Z", + "shell.execute_reply": "2024-09-13T15:53:14.801083Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "%%time\n", + "X.run()" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "pycharm": { + "name": "#%% md\n" + } + }, + "source": [ + "# Processes" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:53:14.805616Z", + "iopub.status.busy": "2024-09-13T15:53:14.805006Z", + "iopub.status.idle": "2024-09-13T15:53:28.075142Z", + "shell.execute_reply": "2024-09-13T15:53:28.074868Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "%%time\n", + "X = Xopt(YAML)\n", + "\n", + "with ProcessPoolExecutor(max_workers=N_CPUS) as executor:\n", + " X.evaluator.executor = executor\n", + " X.evaluator.max_workers = N_CPUS\n", + " X.run()\n", + "len(X.data)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "pycharm": { + "name": "#%% md\n" + } + }, + "source": [ + "# Threads\n", + "\n", + "Continue running, this time with threads." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:53:28.076716Z", + "iopub.status.busy": "2024-09-13T15:53:28.076594Z", + "iopub.status.idle": "2024-09-13T15:53:38.985622Z", + "shell.execute_reply": "2024-09-13T15:53:38.984858Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "%%time\n", + "X = Xopt(YAML)\n", + "\n", + "with ThreadPoolExecutor(max_workers=N_CPUS) as executor:\n", + " X.evaluator.executor = executor\n", + " X.evaluator.max_workers = N_CPUS\n", + " X.run()\n", + "len(X.data)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "pycharm": { + "name": "#%% md\n" + } + }, + "source": [ + "# MPI \n", + "\n", + "The `test.yaml` file completely defines the problem. We will also direct the logging to an `xopt.log` file. The following invocation recruits 4 MPI workers to solve this problem.\n", + "\n", + "We can also continue by calling `.save` with a JSON filename. This will write all of previous results into the file." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:53:38.989702Z", + "iopub.status.busy": "2024-09-13T15:53:38.989391Z", + "iopub.status.idle": "2024-09-13T15:53:39.159372Z", + "shell.execute_reply": "2024-09-13T15:53:39.158752Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "X = Xopt(YAML)\n", + "X.dump(\"test.yaml\") # Write this input to file\n", + "!cat test.yaml" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:53:39.162178Z", + "iopub.status.busy": "2024-09-13T15:53:39.161823Z", + "iopub.status.idle": "2024-09-13T15:53:57.496664Z", + "shell.execute_reply": "2024-09-13T15:53:57.496156Z" + } + }, + "outputs": [], + "source": [ + "%%time\n", + "!mpirun -n 8 python -m mpi4py.futures -m xopt.mpi.run -vv --logfile xopt.log test.yaml" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:53:57.499178Z", + "iopub.status.busy": "2024-09-13T15:53:57.498874Z", + "iopub.status.idle": "2024-09-13T15:53:57.624811Z", + "shell.execute_reply": "2024-09-13T15:53:57.624262Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "!tail xopt.log" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "pycharm": { + "name": "#%% md\n" + } + }, + "source": [ + "# Dask\n", + "\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:53:57.627616Z", + "iopub.status.busy": "2024-09-13T15:53:57.627365Z", + "iopub.status.idle": "2024-09-13T15:53:58.571020Z", + "shell.execute_reply": "2024-09-13T15:53:58.570726Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "client = Client()\n", + "executor = client.get_executor()\n", + "client" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:53:58.572623Z", + "iopub.status.busy": "2024-09-13T15:53:58.572506Z", + "iopub.status.idle": "2024-09-13T15:54:10.653783Z", + "shell.execute_reply": "2024-09-13T15:54:10.653398Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "%%time\n", + "X = Xopt(YAML)\n", + "X.evaluator.executor = executor\n", + "X.evaluator.max_workers = N_CPUS\n", + "X.run()\n", + "len(X.data)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "pycharm": { + "name": "#%% md\n" + } + }, + "source": [ + "# Load output into Pandas\n", + "\n", + "This algorithm writes two types of files: `gen_{i}.json` with all of the new individuals evaluated in a generation, and `pop_{i}.json` with the latest best population. Xopt provides some functions to load these easily into a Pandas dataframe for further analysis." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:54:10.655270Z", + "iopub.status.busy": "2024-09-13T15:54:10.655159Z", + "iopub.status.idle": "2024-09-13T15:54:10.661233Z", + "shell.execute_reply": "2024-09-13T15:54:10.660968Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "X.data" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:54:10.662656Z", + "iopub.status.busy": "2024-09-13T15:54:10.662565Z", + "iopub.status.idle": "2024-09-13T15:54:10.669875Z", + "shell.execute_reply": "2024-09-13T15:54:10.669649Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "df = pd.concat([X.data, X.vocs.feasibility_data(X.data)], axis=1)\n", + "df[df[\"feasible\"]]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:54:10.671305Z", + "iopub.status.busy": "2024-09-13T15:54:10.671199Z", + "iopub.status.idle": "2024-09-13T15:54:10.757506Z", + "shell.execute_reply": "2024-09-13T15:54:10.757195Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "# Plot the feasible ones\n", + "feasible_df = df[df[\"feasible\"]]\n", + "feasible_df.plot(\"y1\", \"y2\", kind=\"scatter\").set_aspect(\"equal\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:54:10.759331Z", + "iopub.status.busy": "2024-09-13T15:54:10.759013Z", + "iopub.status.idle": "2024-09-13T15:54:10.836037Z", + "shell.execute_reply": "2024-09-13T15:54:10.835773Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "# Plot the infeasible ones\n", + "infeasible_df = df[~df[\"feasible\"]]\n", + "infeasible_df.plot(\"y1\", \"y2\", kind=\"scatter\").set_aspect(\"equal\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:54:10.837514Z", + "iopub.status.busy": "2024-09-13T15:54:10.837401Z", + "iopub.status.idle": "2024-09-13T15:54:10.896641Z", + "shell.execute_reply": "2024-09-13T15:54:10.896380Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "# This is the final population\n", + "df1 = X.generator.population\n", + "df1.plot(\"y1\", \"y2\", kind=\"scatter\").set_aspect(\"equal\")" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "pycharm": { + "name": "#%% md\n" + } + }, + "source": [ + "# matplotlib plotting\n", + "\n", + "You can always use matplotlib for customizable plotting" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:54:10.898215Z", + "iopub.status.busy": "2024-09-13T15:54:10.898106Z", + "iopub.status.idle": "2024-09-13T15:54:11.030543Z", + "shell.execute_reply": "2024-09-13T15:54:11.030209Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "# Extract objectives from output\n", + "k1, k2 = \"y1\", \"y2\"\n", + "\n", + "fig, ax = plt.subplots(figsize=(6, 6))\n", + "\n", + "ax.scatter(\n", + " infeasible_df[k1],\n", + " infeasible_df[k2],\n", + " color=\"blue\",\n", + " marker=\".\",\n", + " alpha=0.5,\n", + " label=\"infeasible\",\n", + ")\n", + "ax.scatter(\n", + " feasible_df[k1], feasible_df[k2], color=\"orange\", marker=\".\", label=\"feasible\"\n", + ")\n", + "ax.scatter(df1[k1], df1[k2], color=\"red\", marker=\".\", label=\"final population\")\n", + "ax.set_xlabel(k1)\n", + "ax.set_ylabel(k2)\n", + "ax.set_aspect(\"auto\")\n", + "ax.set_title(\"Xopt's CNSGA algorithm\")\n", + "plt.legend()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:54:11.032351Z", + "iopub.status.busy": "2024-09-13T15:54:11.032009Z", + "iopub.status.idle": "2024-09-13T15:54:11.405742Z", + "shell.execute_reply": "2024-09-13T15:54:11.405356Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "# Cleanup\n", + "#!rm -r dask-worker-space\n", + "!rm -r temp\n", + "!rm xopt.log*\n", + "!rm test.yaml" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + }, + "vscode": { + "interpreter": { + "hash": "4483d4964800812ebc77892a92dde3b54705ec8a224d63d9bb659e2cc457018b" + } + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/basic/xopt_vocs.ipynb b/docs/examples/basic/xopt_vocs.ipynb new file mode 100644 index 0000000..dc6cb3c --- /dev/null +++ b/docs/examples/basic/xopt_vocs.ipynb @@ -0,0 +1,662 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "9700f595", + "metadata": { + "pycharm": { + "name": "#%% md\n" + } + }, + "source": [ + "# VOCS data structure \n", + "\n", + "Variables, Objectives, Constraints, and other Settings (VOCS) helps define our optimization problems. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "32324ac0-b299-42ee-a6b9-e112dfaa5a45", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-27T16:46:04.425862200Z", + "start_time": "2023-10-27T16:46:01.206803200Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:23.378500Z", + "iopub.status.busy": "2024-09-13T15:54:23.378214Z", + "iopub.status.idle": "2024-09-13T15:54:24.383836Z", + "shell.execute_reply": "2024-09-13T15:54:24.383553Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "from xopt.vocs import VOCS\n", + "from xopt.vocs import form_objective_data\n", + "import pandas as pd\n", + "import numpy as np" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "31a15253-14cd-4547-ab01-09f4b56f5bf5", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-27T16:46:04.440220800Z", + "start_time": "2023-10-27T16:46:04.427862900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:24.385474Z", + "iopub.status.busy": "2024-09-13T15:54:24.385365Z", + "iopub.status.idle": "2024-09-13T15:54:24.389440Z", + "shell.execute_reply": "2024-09-13T15:54:24.389205Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "Y = \"\"\"\n", + "variables:\n", + " a: [0, 1e3] # Note that 1e3 usually parses as a str with YAML. \n", + " b: [-1, 1]\n", + "objectives:\n", + " c: maximize\n", + " d: minimize \n", + "constraints:\n", + " e: ['Less_than', 2]\n", + " f: ['greater_than', 0]\n", + "constants:\n", + " g: 1234\n", + "\n", + "\"\"\"\n", + "\n", + "vocs = VOCS.from_yaml(Y)\n", + "vocs" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "304bcc89", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-27T16:46:04.484822200Z", + "start_time": "2023-10-27T16:46:04.442248900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:24.390834Z", + "iopub.status.busy": "2024-09-13T15:54:24.390728Z", + "iopub.status.idle": "2024-09-13T15:54:24.392869Z", + "shell.execute_reply": "2024-09-13T15:54:24.392654Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "# as dict\n", + "dict(vocs)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "b236bfb4", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-27T16:46:04.493762900Z", + "start_time": "2023-10-27T16:46:04.458284400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:24.394199Z", + "iopub.status.busy": "2024-09-13T15:54:24.394090Z", + "iopub.status.idle": "2024-09-13T15:54:24.395693Z", + "shell.execute_reply": "2024-09-13T15:54:24.395474Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "# re-parse dict\n", + "vocs2 = VOCS.from_dict(dict(vocs))" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "76c9a173", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-27T16:46:04.493762900Z", + "start_time": "2023-10-27T16:46:04.471285600Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:24.396935Z", + "iopub.status.busy": "2024-09-13T15:54:24.396858Z", + "iopub.status.idle": "2024-09-13T15:54:24.398815Z", + "shell.execute_reply": "2024-09-13T15:54:24.398561Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "# Check that these are the same\n", + "vocs2 == vocs" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "6a846f4d", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-27T16:46:04.503771300Z", + "start_time": "2023-10-27T16:46:04.486737500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:24.400062Z", + "iopub.status.busy": "2024-09-13T15:54:24.399983Z", + "iopub.status.idle": "2024-09-13T15:54:24.402060Z", + "shell.execute_reply": "2024-09-13T15:54:24.401833Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "# This replaces the old vocs[\"variables\"]\n", + "getattr(vocs, \"variables\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "6fa2afc8", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-27T16:46:04.544770800Z", + "start_time": "2023-10-27T16:46:04.504768500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:24.403350Z", + "iopub.status.busy": "2024-09-13T15:54:24.403277Z", + "iopub.status.idle": "2024-09-13T15:54:24.405301Z", + "shell.execute_reply": "2024-09-13T15:54:24.405056Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "vocs.objectives[\"c\"] == \"MAXIMIZE\"" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "713272b7", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-27T16:46:04.544770800Z", + "start_time": "2023-10-27T16:46:04.518770200Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:24.406554Z", + "iopub.status.busy": "2024-09-13T15:54:24.406478Z", + "iopub.status.idle": "2024-09-13T15:54:24.408554Z", + "shell.execute_reply": "2024-09-13T15:54:24.408340Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "# json\n", + "vocs.to_json()" + ] + }, + { + "cell_type": "markdown", + "id": "11167a85", + "metadata": { + "pycharm": { + "name": "#%% md\n" + } + }, + "source": [ + "# Objective Evaluation" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "c4d150be", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-27T16:46:04.566771500Z", + "start_time": "2023-10-27T16:46:04.534772500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:24.409883Z", + "iopub.status.busy": "2024-09-13T15:54:24.409801Z", + "iopub.status.idle": "2024-09-13T15:54:24.416749Z", + "shell.execute_reply": "2024-09-13T15:54:24.416537Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "data = pd.DataFrame(vocs.random_inputs(10))\n", + "# Add some outputs\n", + "data[\"c\"] = data[\"a\"] + data[\"b\"]\n", + "data[\"d\"] = data[\"a\"] - data[\"b\"]\n", + "data[\"e\"] = data[\"a\"] * 2 + data[\"b\"] * 2\n", + "data[\"f\"] = data[\"a\"] * 2 - data[\"b\"] * 2\n", + "data.index = np.arange(len(data)) + 5 # custom index\n", + "data" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "a695dc98", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-27T16:46:04.604993200Z", + "start_time": "2023-10-27T16:46:04.563770500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:24.418098Z", + "iopub.status.busy": "2024-09-13T15:54:24.418016Z", + "iopub.status.idle": "2024-09-13T15:54:24.420079Z", + "shell.execute_reply": "2024-09-13T15:54:24.419867Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "vocs.objectives" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "43051b71", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-27T16:46:04.635082700Z", + "start_time": "2023-10-27T16:46:04.582806500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:24.421354Z", + "iopub.status.busy": "2024-09-13T15:54:24.421273Z", + "iopub.status.idle": "2024-09-13T15:54:24.424690Z", + "shell.execute_reply": "2024-09-13T15:54:24.424477Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "# These are in standard form for minimization\n", + "form_objective_data(vocs.objectives, data)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2ed50815", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-27T16:46:04.635997800Z", + "start_time": "2023-10-27T16:46:04.592809200Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:24.425955Z", + "iopub.status.busy": "2024-09-13T15:54:24.425881Z", + "iopub.status.idle": "2024-09-13T15:54:24.429058Z", + "shell.execute_reply": "2024-09-13T15:54:24.428830Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "# This is also available as a method\n", + "vocs.objective_data(data)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "9f4275d4", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-27T16:46:04.665088600Z", + "start_time": "2023-10-27T16:46:04.607996700Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:24.430318Z", + "iopub.status.busy": "2024-09-13T15:54:24.430228Z", + "iopub.status.idle": "2024-09-13T15:54:24.432664Z", + "shell.execute_reply": "2024-09-13T15:54:24.432450Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "# use the to_numpy() method to convert for low level use.\n", + "vocs.objective_data(data).to_numpy()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "29b73df4", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-27T16:46:04.702034Z", + "start_time": "2023-10-27T16:46:04.622998Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:24.433958Z", + "iopub.status.busy": "2024-09-13T15:54:24.433875Z", + "iopub.status.idle": "2024-09-13T15:54:24.437333Z", + "shell.execute_reply": "2024-09-13T15:54:24.437135Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "vocs.constraint_data(data)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "e46a5e83", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-27T16:46:04.703032900Z", + "start_time": "2023-10-27T16:46:04.642000500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:24.438649Z", + "iopub.status.busy": "2024-09-13T15:54:24.438572Z", + "iopub.status.idle": "2024-09-13T15:54:24.442669Z", + "shell.execute_reply": "2024-09-13T15:54:24.442443Z" + }, + "pycharm": { + "name": "#%%\n" + } + }, + "outputs": [], + "source": [ + "vocs.feasibility_data(data)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "c42dfa48", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-27T16:46:04.703032900Z", + "start_time": "2023-10-27T16:46:04.665088600Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:24.443972Z", + "iopub.status.busy": "2024-09-13T15:54:24.443881Z", + "iopub.status.idle": "2024-09-13T15:54:24.447077Z", + "shell.execute_reply": "2024-09-13T15:54:24.446871Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# normalize inputs to unit domain [0,1]\n", + "normed_data = vocs.normalize_inputs(data)\n", + "normed_data" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "7364e86b", + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:54:24.448319Z", + "iopub.status.busy": "2024-09-13T15:54:24.448238Z", + "iopub.status.idle": "2024-09-13T15:54:24.451434Z", + "shell.execute_reply": "2024-09-13T15:54:24.451213Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# and denormalize\n", + "vocs.denormalize_inputs(normed_data)" + ] + }, + { + "cell_type": "markdown", + "id": "59041be7", + "metadata": {}, + "source": [ + "# Error handling" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "f9171ede", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-27T16:46:04.719064600Z", + "start_time": "2023-10-27T16:46:04.668031Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:24.452750Z", + "iopub.status.busy": "2024-09-13T15:54:24.452676Z", + "iopub.status.idle": "2024-09-13T15:54:24.454842Z", + "shell.execute_reply": "2024-09-13T15:54:24.454623Z" + } + }, + "outputs": [], + "source": [ + "Y = \"\"\"\n", + "variables:\n", + " a: [0, 1e3] # Note that 1e3 usually parses as a str with YAML. \n", + " b: [-1, 1]\n", + "objectives:\n", + " c: maximize\n", + " d: minimize \n", + "constraints:\n", + " e: ['Less_than', 2]\n", + " f: ['greater_than', 0]\n", + "constants:\n", + " g: 1234\n", + "\n", + "\"\"\"\n", + "\n", + "vocs = VOCS.from_yaml(Y)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "b5513539", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-27T16:46:04.763060700Z", + "start_time": "2023-10-27T16:46:04.686996500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:24.455998Z", + "iopub.status.busy": "2024-09-13T15:54:24.455925Z", + "iopub.status.idle": "2024-09-13T15:54:24.458659Z", + "shell.execute_reply": "2024-09-13T15:54:24.458429Z" + } + }, + "outputs": [], + "source": [ + "d = {\"a\": [1, 2, 3]}\n", + "\n", + "df = pd.DataFrame(d)\n", + "df2 = pd.DataFrame(df).copy()\n", + "\n", + "df2[\"b\"] = np.nan\n", + "df2[\"b\"] - 1" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "30f3b3b4", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-27T16:46:04.800032400Z", + "start_time": "2023-10-27T16:46:04.698034700Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:24.459913Z", + "iopub.status.busy": "2024-09-13T15:54:24.459836Z", + "iopub.status.idle": "2024-09-13T15:54:24.461545Z", + "shell.execute_reply": "2024-09-13T15:54:24.461348Z" + } + }, + "outputs": [], + "source": [ + "data[\"a\"] = np.nan" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "6393376b", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-27T16:46:04.877099700Z", + "start_time": "2023-10-27T16:46:04.715062Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:24.462904Z", + "iopub.status.busy": "2024-09-13T15:54:24.462822Z", + "iopub.status.idle": "2024-09-13T15:54:24.464843Z", + "shell.execute_reply": "2024-09-13T15:54:24.464636Z" + } + }, + "outputs": [], + "source": [ + "a = 2\n", + "\n", + "\n", + "def f(x=a):\n", + " return x\n", + "\n", + "\n", + "a = 99\n", + "f()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "cb0ecd74", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-27T16:46:04.880100300Z", + "start_time": "2023-10-27T16:46:04.728063600Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:24.466048Z", + "iopub.status.busy": "2024-09-13T15:54:24.465972Z", + "iopub.status.idle": "2024-09-13T15:54:24.468950Z", + "shell.execute_reply": "2024-09-13T15:54:24.468730Z" + } + }, + "outputs": [], + "source": [ + "pd.DataFrame(6e66, index=[1, 2, 3], columns=[\"A\"])" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "88bb8253", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-27T16:46:04.896129200Z", + "start_time": "2023-10-27T16:46:04.744036400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:24.470167Z", + "iopub.status.busy": "2024-09-13T15:54:24.470092Z", + "iopub.status.idle": "2024-09-13T15:54:24.473523Z", + "shell.execute_reply": "2024-09-13T15:54:24.473268Z" + } + }, + "outputs": [], + "source": [ + "# These are in standard form for minimization\n", + "\n", + "data = pd.DataFrame({\"c\": [1, 2, 3, 4]}, index=[9, 3, 4, 5])\n", + "\n", + "form_objective_data(vocs.objectives, data)" + ] + } + ], + "metadata": { + "interpreter": { + "hash": "60703f99bc9a1e465ed9e894ac1e8f256837fa55699b4912a7939def4ae95691" + }, + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/examples/bayes_exp/bayesian_exploration.ipynb b/docs/examples/bayes_exp/bayesian_exploration.ipynb new file mode 100644 index 0000000..3c78a51 --- /dev/null +++ b/docs/examples/bayes_exp/bayesian_exploration.ipynb @@ -0,0 +1,315 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "# Bayesian Exploration\n", + "Here we demonstrate the use of Bayesian Exploration to characterize an unknown\n", + "function in the presence of constraints (see [here](https://www.nature.com/articles/s41467-021-25757-3)).\n", + "The function we wish to explore is the first objective of the TNK test problem." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Specifiying generator options\n", + "We start with the generator defaults and modify as needed for conservative\n", + "exploration, which should prevent any constraint violations." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:49:35.830514Z", + "iopub.status.busy": "2024-09-13T15:49:35.830266Z", + "iopub.status.idle": "2024-09-13T15:49:37.500740Z", + "shell.execute_reply": "2024-09-13T15:49:37.500445Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# set values if testing\n", + "import os\n", + "\n", + "from copy import deepcopy\n", + "from xopt import Xopt, Evaluator\n", + "from xopt.generators.bayesian import BayesianExplorationGenerator\n", + "from xopt.resources.test_functions.tnk import evaluate_TNK, tnk_vocs\n", + "\n", + "# Ignore all warnings\n", + "import warnings\n", + "\n", + "warnings.filterwarnings(\"ignore\")\n", + "\n", + "SMOKE_TEST = os.environ.get(\"SMOKE_TEST\")\n", + "NUM_MC_SAMPLES = 1 if SMOKE_TEST else 128\n", + "NUM_RESTARTS = 1 if SMOKE_TEST else 20\n", + "\n", + "vocs = deepcopy(tnk_vocs)\n", + "vocs.objectives = {}\n", + "vocs.observables = [\"y1\"]\n", + "\n", + "generator = BayesianExplorationGenerator(vocs=vocs)\n", + "generator.max_travel_distances = [0.25, 0.25]\n", + "generator.numerical_optimizer.n_restarts = NUM_RESTARTS\n", + "generator.n_monte_carlo_samples = NUM_MC_SAMPLES\n", + "\n", + "evaluator = Evaluator(function=evaluate_TNK)\n", + "\n", + "X = Xopt(generator=generator, evaluator=evaluator, vocs=vocs)\n", + "X" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Run exploration\n", + "We start with evaluating 2 points that we know satisfy the constraints. We then run\n", + "30 exploration steps." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:49:37.522962Z", + "iopub.status.busy": "2024-09-13T15:49:37.522764Z", + "iopub.status.idle": "2024-09-13T15:49:37.530412Z", + "shell.execute_reply": "2024-09-13T15:49:37.530171Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "X.evaluate_data({\"x1\": [1.0, 0.75], \"x2\": [0.7, 0.95]})" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:49:37.531732Z", + "iopub.status.busy": "2024-09-13T15:49:37.531635Z", + "iopub.status.idle": "2024-09-13T15:49:39.055235Z", + "shell.execute_reply": "2024-09-13T15:49:39.054797Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "for i in range(2):\n", + " print(f\"step {i}\")\n", + " X.step()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:49:39.056947Z", + "iopub.status.busy": "2024-09-13T15:49:39.056826Z", + "iopub.status.idle": "2024-09-13T15:49:39.060928Z", + "shell.execute_reply": "2024-09-13T15:49:39.060709Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# view the data\n", + "X.data" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:49:39.062334Z", + "iopub.status.busy": "2024-09-13T15:49:39.062246Z", + "iopub.status.idle": "2024-09-13T15:49:39.408101Z", + "shell.execute_reply": "2024-09-13T15:49:39.407782Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# plot results\n", + "ax = X.data.plot(\"x1\", \"x2\")\n", + "ax.set_aspect(\"equal\")" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Introspect models, acquisition function and feasibility prediction\n", + "During exploration we generate Gaussian Process models of each objective and\n", + "constraint. We demonstrate how they are viewed below." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:49:39.409688Z", + "iopub.status.busy": "2024-09-13T15:49:39.409537Z", + "iopub.status.idle": "2024-09-13T15:49:40.596506Z", + "shell.execute_reply": "2024-09-13T15:49:40.596197Z" + } + }, + "outputs": [], + "source": [ + "fig, ax = X.generator.visualize_model(show_feasibility=True, n_grid=100)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Generator model hyperparameters" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:49:40.599399Z", + "iopub.status.busy": "2024-09-13T15:49:40.599290Z", + "iopub.status.idle": "2024-09-13T15:49:40.604079Z", + "shell.execute_reply": "2024-09-13T15:49:40.603845Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# print generator model hyperparameters\n", + "for name, val in X.generator.model.named_parameters():\n", + " print(f\"{name}:{val}\")\n", + "\n", + "X.generator.model.models[2].covar_module.lengthscale" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Examine the number of constraint violations\n", + "Using the convience function provided by the vocs object we can evaluate which\n", + "samples violate either or both of our constraints." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:49:40.605375Z", + "iopub.status.busy": "2024-09-13T15:49:40.605292Z", + "iopub.status.idle": "2024-09-13T15:49:40.609674Z", + "shell.execute_reply": "2024-09-13T15:49:40.609461Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "X.vocs.feasibility_data(X.data)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:49:40.611135Z", + "iopub.status.busy": "2024-09-13T15:49:40.611035Z", + "iopub.status.idle": "2024-09-13T15:49:41.732575Z", + "shell.execute_reply": "2024-09-13T15:49:41.732305Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# generate next point\n", + "X.generator.generate(1)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/bayes_exp/bayesian_exploration_from_yaml.ipynb b/docs/examples/bayes_exp/bayesian_exploration_from_yaml.ipynb new file mode 100644 index 0000000..b8f6b6b --- /dev/null +++ b/docs/examples/bayes_exp/bayesian_exploration_from_yaml.ipynb @@ -0,0 +1,208 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Bayesian exploration from YAML" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-06-27T15:40:58.222341700Z", + "start_time": "2023-06-27T15:40:49.783378500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:50:02.293334Z", + "iopub.status.busy": "2024-09-13T15:50:02.293007Z", + "iopub.status.idle": "2024-09-13T15:50:03.279640Z", + "shell.execute_reply": "2024-09-13T15:50:03.279335Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "from xopt import Xopt\n", + "\n", + "# set values if testing\n", + "import os\n", + "\n", + "import warnings\n", + "\n", + "warnings.filterwarnings(\"ignore\")\n", + "\n", + "\n", + "SMOKE_TEST = os.environ.get(\"SMOKE_TEST\")\n", + "\n", + "YAML = \"\"\"\n", + "generator:\n", + " name: bayesian_exploration\n", + "\n", + "evaluator:\n", + " function: xopt.resources.test_functions.tnk.evaluate_TNK\n", + "\n", + "vocs:\n", + " variables:\n", + " x1: [0, 3.14159]\n", + " x2: [0, 3.14159]\n", + " observables: [y1]\n", + " constraints:\n", + " c1: [GREATER_THAN, 0]\n", + " c2: [LESS_THAN, 0.5]\n", + " constants: {a: dummy_constant}\n", + "\n", + "\"\"\"" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-06-27T15:40:58.279371300Z", + "start_time": "2023-06-27T15:40:58.223342400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:50:03.281449Z", + "iopub.status.busy": "2024-09-13T15:50:03.281310Z", + "iopub.status.idle": "2024-09-13T15:50:03.870248Z", + "shell.execute_reply": "2024-09-13T15:50:03.869883Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "X = Xopt.from_yaml(YAML)\n", + "\n", + "# for testing purposes only\n", + "if SMOKE_TEST:\n", + " X.generator.numerical_optimizer.n_restarts = 1\n", + " X.generator.n_monte_carlo_samples = 1\n", + "\n", + "X" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-06-27T15:41:47.000398300Z", + "start_time": "2023-06-27T15:40:58.255341800Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:50:03.891525Z", + "iopub.status.busy": "2024-09-13T15:50:03.891330Z", + "iopub.status.idle": "2024-09-13T15:50:21.303719Z", + "shell.execute_reply": "2024-09-13T15:50:21.303365Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "X.random_evaluate(5)\n", + "\n", + "for i in range(5):\n", + " print(f\"step {i}\")\n", + " X.step()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-06-27T15:41:47.016401600Z", + "start_time": "2023-06-27T15:41:47.002399Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:50:21.305548Z", + "iopub.status.busy": "2024-09-13T15:50:21.305362Z", + "iopub.status.idle": "2024-09-13T15:50:21.309628Z", + "shell.execute_reply": "2024-09-13T15:50:21.309368Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "print(X.data)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-06-27T15:41:47.949659600Z", + "start_time": "2023-06-27T15:41:47.017428500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:50:21.311002Z", + "iopub.status.busy": "2024-09-13T15:50:21.310915Z", + "iopub.status.idle": "2024-09-13T15:50:21.641630Z", + "shell.execute_reply": "2024-09-13T15:50:21.641351Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# plot results\n", + "ax = X.data.plot(\"x1\", \"x2\")\n", + "ax.set_aspect(\"equal\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:50:21.643202Z", + "iopub.status.busy": "2024-09-13T15:50:21.643041Z", + "iopub.status.idle": "2024-09-13T15:50:22.876968Z", + "shell.execute_reply": "2024-09-13T15:50:22.876653Z" + } + }, + "outputs": [], + "source": [ + "fig, ax = X.generator.visualize_model(show_feasibility=True, n_grid=100)" + ] + } + ], + "metadata": { + "interpreter": { + "hash": "72034539424920dfb606fe3b820b3f27dca0cbf1c69938110810ec4641e275b1" + }, + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/bayes_exp/bayesian_exploration_w_interpolation.ipynb b/docs/examples/bayes_exp/bayesian_exploration_w_interpolation.ipynb new file mode 100644 index 0000000..fa2231c --- /dev/null +++ b/docs/examples/bayes_exp/bayesian_exploration_w_interpolation.ipynb @@ -0,0 +1,353 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "# Bayesian Exploration\n", + "Here we demonstrate the use of Bayesian Exploration to characterize an unknown\n", + "function in the presence of constraints (see [here](https://www.nature.com/articles/s41467-021-25757-3)).\n", + "The function we wish to explore is the first objective of the TNK test problem." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Specifiying generator options\n", + "We start with the generator defaults and modify as needed for conservative\n", + "exploration, which should prevent any constraint violations." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-11-14T21:38:27.504548300Z", + "start_time": "2023-11-14T21:38:24.272273500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:49:43.989564Z", + "iopub.status.busy": "2024-09-13T15:49:43.989239Z", + "iopub.status.idle": "2024-09-13T15:49:45.516807Z", + "shell.execute_reply": "2024-09-13T15:49:45.516507Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# set values if testing\n", + "import os\n", + "\n", + "from copy import deepcopy\n", + "from xopt import Xopt, Evaluator\n", + "from xopt.generators.bayesian import BayesianExplorationGenerator\n", + "from xopt.resources.test_functions.tnk import evaluate_TNK, tnk_vocs\n", + "\n", + "# Ignore all warnings\n", + "import warnings\n", + "\n", + "warnings.filterwarnings(\"ignore\")\n", + "\n", + "SMOKE_TEST = os.environ.get(\"SMOKE_TEST\")\n", + "NUM_MC_SAMPLES = 1 if SMOKE_TEST else 128\n", + "NUM_RESTARTS = 1 if SMOKE_TEST else 20\n", + "\n", + "\n", + "vocs = deepcopy(tnk_vocs)\n", + "vocs.objectives = {}\n", + "vocs.observables = [\"y1\"]\n", + "\n", + "generator = BayesianExplorationGenerator(vocs=vocs)\n", + "generator.numerical_optimizer.n_restarts = NUM_RESTARTS\n", + "generator.numerical_optimizer.max_iter = 100\n", + "generator.n_monte_carlo_samples = NUM_MC_SAMPLES\n", + "generator.n_interpolate_points = 5\n", + "\n", + "evaluator = Evaluator(function=evaluate_TNK)\n", + "\n", + "X = Xopt(generator=generator, evaluator=evaluator, vocs=vocs)\n", + "X" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Run exploration\n", + "We start with evaluating 2 points that we know satisfy the constraints. We then run\n", + "30 exploration steps." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-11-14T21:38:27.547546500Z", + "start_time": "2023-11-14T21:38:27.506549300Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:49:45.538126Z", + "iopub.status.busy": "2024-09-13T15:49:45.537933Z", + "iopub.status.idle": "2024-09-13T15:49:45.545152Z", + "shell.execute_reply": "2024-09-13T15:49:45.544914Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "X.evaluate_data({\"x1\": [1.0, 0.75], \"x2\": [0.7, 0.95]})" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-11-14T21:38:58.405527100Z", + "start_time": "2023-11-14T21:38:27.520548400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:49:45.546556Z", + "iopub.status.busy": "2024-09-13T15:49:45.546482Z", + "iopub.status.idle": "2024-09-13T15:49:57.580498Z", + "shell.execute_reply": "2024-09-13T15:49:57.580185Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "for i in range(20):\n", + " print(f\"step {i}\")\n", + " X.step()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-11-14T21:38:58.420527100Z", + "start_time": "2023-11-14T21:38:58.414526900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:49:57.582464Z", + "iopub.status.busy": "2024-09-13T15:49:57.582292Z", + "iopub.status.idle": "2024-09-13T15:49:57.587523Z", + "shell.execute_reply": "2024-09-13T15:49:57.587314Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# view the data\n", + "X.data" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-11-14T21:38:58.961213100Z", + "start_time": "2023-11-14T21:38:58.421527Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:49:57.588870Z", + "iopub.status.busy": "2024-09-13T15:49:57.588789Z", + "iopub.status.idle": "2024-09-13T15:49:57.921151Z", + "shell.execute_reply": "2024-09-13T15:49:57.920906Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# plot results\n", + "ax = X.data.plot(\"x1\", \"x2\")\n", + "ax.set_aspect(\"equal\")" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Introspect models, acquisition function and feasibility prediction\n", + "During exploration we generate Gaussian Process models of each objective and\n", + "constraint. We demonstrate how they are viewed below." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-11-14T21:39:03.161691600Z", + "start_time": "2023-11-14T21:38:58.962214700Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:49:57.922739Z", + "iopub.status.busy": "2024-09-13T15:49:57.922598Z", + "iopub.status.idle": "2024-09-13T15:49:59.442036Z", + "shell.execute_reply": "2024-09-13T15:49:59.441725Z" + } + }, + "outputs": [], + "source": [ + "fig, ax = X.generator.visualize_model(show_feasibility=True, n_grid=100)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Generator model hyperparameters" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-11-14T21:39:03.220691400Z", + "start_time": "2023-11-14T21:39:03.162691600Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:49:59.445523Z", + "iopub.status.busy": "2024-09-13T15:49:59.445390Z", + "iopub.status.idle": "2024-09-13T15:49:59.450445Z", + "shell.execute_reply": "2024-09-13T15:49:59.450139Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# print generator model hyperparameters\n", + "for name, val in X.generator.model.named_parameters():\n", + " print(f\"{name}:{val}\")\n", + "\n", + "X.generator.model.models[2].covar_module.lengthscale" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Examine the number of constraint violations\n", + "Using the convience function provided by the vocs object we can evaluate which\n", + "samples violate either or both of our constraints." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-11-14T21:39:03.234692100Z", + "start_time": "2023-11-14T21:39:03.177693800Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:49:59.451848Z", + "iopub.status.busy": "2024-09-13T15:49:59.451765Z", + "iopub.status.idle": "2024-09-13T15:49:59.456690Z", + "shell.execute_reply": "2024-09-13T15:49:59.456447Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "X.vocs.feasibility_data(X.data)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-11-14T21:39:04.225690600Z", + "start_time": "2023-11-14T21:39:03.192694800Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:49:59.457977Z", + "iopub.status.busy": "2024-09-13T15:49:59.457892Z", + "iopub.status.idle": "2024-09-13T15:50:00.022176Z", + "shell.execute_reply": "2024-09-13T15:50:00.021807Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# generate next point\n", + "X.generator.generate(1)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/bayes_exp/bayesian_exploration_with_nans.ipynb b/docs/examples/bayes_exp/bayesian_exploration_with_nans.ipynb new file mode 100644 index 0000000..131ef47 --- /dev/null +++ b/docs/examples/bayes_exp/bayesian_exploration_with_nans.ipynb @@ -0,0 +1,232 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Bayesian Exploration with NaNs\n", + "\n", + "As violations of constraints can lead to invalid values of the objective, the evaluate function may simply return NaNs. We demonstrate below how we can still perform Bayesian Exploration in that case." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-06-14T15:37:25.535638700Z", + "start_time": "2023-06-14T15:37:22.379218300Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:50:25.160005Z", + "iopub.status.busy": "2024-09-13T15:50:25.159647Z", + "iopub.status.idle": "2024-09-13T15:50:26.672325Z", + "shell.execute_reply": "2024-09-13T15:50:26.671836Z" + } + }, + "outputs": [], + "source": [ + "# set values if testing\n", + "import os\n", + "\n", + "import pandas as pd\n", + "import torch\n", + "from copy import deepcopy\n", + "from xopt import Xopt, Evaluator\n", + "from xopt.generators.bayesian import BayesianExplorationGenerator\n", + "from xopt.resources.test_functions.tnk import evaluate_TNK, tnk_vocs\n", + "\n", + "# Ignore all warnings\n", + "import warnings\n", + "\n", + "warnings.filterwarnings(\"ignore\")\n", + "\n", + "SMOKE_TEST = os.environ.get(\"SMOKE_TEST\")\n", + "NUM_MC_SAMPLES = 1 if SMOKE_TEST else 128\n", + "NUM_RESTARTS = 1 if SMOKE_TEST else 20\n", + "\n", + "vocs = deepcopy(tnk_vocs)\n", + "vocs.objectives = {}\n", + "vocs.observables = [\"y1\"]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-06-14T15:37:25.549637200Z", + "start_time": "2023-06-14T15:37:25.539666500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:50:26.674126Z", + "iopub.status.busy": "2024-09-13T15:50:26.673966Z", + "iopub.status.idle": "2024-09-13T15:50:26.676329Z", + "shell.execute_reply": "2024-09-13T15:50:26.676082Z" + } + }, + "outputs": [], + "source": [ + "# modify the evaluate function to return NaNs if constraints are violated\n", + "def evaluate(input_dict):\n", + " output_dict = evaluate_TNK(input_dict)\n", + " del output_dict[\"y2\"]\n", + " for c in vocs.constraints.keys():\n", + " if (\n", + " vocs.constraints[c][0].upper() == \"GREATER_THAN\"\n", + " and output_dict[c] <= vocs.constraints[c][1]\n", + " ):\n", + " output_dict[\"y1\"] = torch.nan\n", + " elif (\n", + " vocs.constraints[c][0].upper() == \"LESS_THAN\"\n", + " and output_dict[c] >= vocs.constraints[c][1]\n", + " ):\n", + " output_dict[\"y1\"] = torch.nan\n", + " return output_dict" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-06-14T15:37:25.580538800Z", + "start_time": "2023-06-14T15:37:25.552636600Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:50:26.677735Z", + "iopub.status.busy": "2024-09-13T15:50:26.677632Z", + "iopub.status.idle": "2024-09-13T15:50:26.685490Z", + "shell.execute_reply": "2024-09-13T15:50:26.685270Z" + } + }, + "outputs": [], + "source": [ + "generator = BayesianExplorationGenerator(vocs=vocs)\n", + "generator.max_travel_distances = [0.25, 0.25]\n", + "generator.n_monte_carlo_samples = NUM_MC_SAMPLES\n", + "generator.numerical_optimizer.n_restarts = NUM_RESTARTS\n", + "\n", + "evaluator = Evaluator(function=evaluate)\n", + "X = Xopt(generator=generator, evaluator=evaluator, vocs=vocs)\n", + "X" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Run exploration\n", + "We start with evaluating 2 points that we know satisfy the constraints. We then run\n", + "30 exploration steps." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-06-14T15:37:25.638907100Z", + "start_time": "2023-06-14T15:37:25.582541Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:50:26.706489Z", + "iopub.status.busy": "2024-09-13T15:50:26.706373Z", + "iopub.status.idle": "2024-09-13T15:50:26.713499Z", + "shell.execute_reply": "2024-09-13T15:50:26.713266Z" + } + }, + "outputs": [], + "source": [ + "X.evaluate_data(pd.DataFrame({\"x1\": [1.0, 0.75], \"x2\": [0.7, 0.95]}))" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-06-14T15:42:05.755461900Z", + "start_time": "2023-06-14T15:37:25.611873400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:50:26.714870Z", + "iopub.status.busy": "2024-09-13T15:50:26.714785Z", + "iopub.status.idle": "2024-09-13T15:51:09.297672Z", + "shell.execute_reply": "2024-09-13T15:51:09.297339Z" + } + }, + "outputs": [], + "source": [ + "N_STEPS = 1 if SMOKE_TEST else 30\n", + "for i in range(N_STEPS):\n", + " print(f\"step {i}\")\n", + " X.step()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-06-14T15:42:05.786611100Z", + "start_time": "2023-06-14T15:42:05.773463300Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:51:09.299490Z", + "iopub.status.busy": "2024-09-13T15:51:09.299336Z", + "iopub.status.idle": "2024-09-13T15:51:09.305496Z", + "shell.execute_reply": "2024-09-13T15:51:09.305264Z" + } + }, + "outputs": [], + "source": [ + "# view the data\n", + "X.data" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-06-14T15:42:06.400652600Z", + "start_time": "2023-06-14T15:42:05.787612700Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:51:09.306861Z", + "iopub.status.busy": "2024-09-13T15:51:09.306776Z", + "iopub.status.idle": "2024-09-13T15:51:09.645048Z", + "shell.execute_reply": "2024-09-13T15:51:09.644777Z" + } + }, + "outputs": [], + "source": [ + "# plot results\n", + "ax = X.data.plot(\"x1\", \"x2\")\n", + "ax.set_aspect(\"equal\")" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/ga/cnsga_tnk.ipynb b/docs/examples/ga/cnsga_tnk.ipynb new file mode 100644 index 0000000..c931a2b --- /dev/null +++ b/docs/examples/ga/cnsga_tnk.ipynb @@ -0,0 +1,688 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Xopt CNSGA algorithm" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T21:51:52.453021600Z", + "start_time": "2023-09-06T21:51:49.273323Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T16:00:01.585855Z", + "iopub.status.busy": "2024-09-13T16:00:01.585522Z", + "iopub.status.idle": "2024-09-13T16:00:02.749698Z", + "shell.execute_reply": "2024-09-13T16:00:02.749434Z" + } + }, + "outputs": [], + "source": [ + "from xopt.generators.ga.cnsga import CNSGAGenerator\n", + "\n", + "from xopt.resources.test_functions.tnk import evaluate_TNK, tnk_vocs\n", + "\n", + "from xopt.utils import read_xopt_csv\n", + "\n", + "from xopt import Xopt, Evaluator\n", + "\n", + "import pandas as pd\n", + "\n", + "from glob import glob\n", + "\n", + "import matplotlib.pyplot as plt" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T21:51:52.469030800Z", + "start_time": "2023-09-06T21:51:52.449951900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T16:00:02.751723Z", + "iopub.status.busy": "2024-09-13T16:00:02.751521Z", + "iopub.status.idle": "2024-09-13T16:00:02.753525Z", + "shell.execute_reply": "2024-09-13T16:00:02.753086Z" + } + }, + "outputs": [], + "source": [ + "# Useful for debugging\n", + "# %load_ext autoreload\n", + "# %autoreload 2" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T21:51:52.493030800Z", + "start_time": "2023-09-06T21:51:52.465030400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T16:00:02.755254Z", + "iopub.status.busy": "2024-09-13T16:00:02.755117Z", + "iopub.status.idle": "2024-09-13T16:00:02.759971Z", + "shell.execute_reply": "2024-09-13T16:00:02.759724Z" + } + }, + "outputs": [], + "source": [ + "ev = Evaluator(function=evaluate_TNK)\n", + "ev.function_kwargs = {\n", + " \"raise_probability\": 0.1\n", + "} # optional random crashing, to mimic real-world use." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T21:51:52.509029400Z", + "start_time": "2023-09-06T21:51:52.495029300Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T16:00:02.761413Z", + "iopub.status.busy": "2024-09-13T16:00:02.761328Z", + "iopub.status.idle": "2024-09-13T16:00:02.763167Z", + "shell.execute_reply": "2024-09-13T16:00:02.762928Z" + } + }, + "outputs": [], + "source": [ + "X = Xopt(\n", + " generator=CNSGAGenerator(vocs=tnk_vocs),\n", + " evaluator=ev,\n", + " vocs=tnk_vocs,\n", + ")\n", + "X.strict = False" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "tags": [] + }, + "source": [ + "Run 100 generations" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T21:51:57.548278900Z", + "start_time": "2023-09-06T21:51:52.510031300Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T16:00:02.764555Z", + "iopub.status.busy": "2024-09-13T16:00:02.764469Z", + "iopub.status.idle": "2024-09-13T16:00:04.262400Z", + "shell.execute_reply": "2024-09-13T16:00:04.262090Z" + } + }, + "outputs": [], + "source": [ + "%%time\n", + "for _ in range(64 * 20):\n", + " X.step()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Plot " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T21:51:58.011277600Z", + "start_time": "2023-09-06T21:51:57.986277600Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T16:00:04.283246Z", + "iopub.status.busy": "2024-09-13T16:00:04.283105Z", + "iopub.status.idle": "2024-09-13T16:00:04.285630Z", + "shell.execute_reply": "2024-09-13T16:00:04.285358Z" + } + }, + "outputs": [], + "source": [ + "def plot_population(X):\n", + " fig, ax = plt.subplots(figsize=(8, 8))\n", + "\n", + " fdata = tnk_vocs.feasibility_data(X.data)\n", + "\n", + " k1 = \"x1\"\n", + " k2 = \"x2\"\n", + "\n", + " X.data.plot.scatter(k1, k2, marker=\".\", alpha=0.1, color=\"black\", ax=ax)\n", + " X.data[fdata[\"feasible\"]].plot.scatter(\n", + " k1, k2, marker=\"x\", alpha=0.3, color=\"orange\", ax=ax\n", + " )\n", + " X.generator.population.plot.scatter(k1, k2, marker=\"o\", color=\"red\", alpha=1, ax=ax)\n", + " ax.set_xlabel(k1)\n", + " ax.set_ylabel(k2)\n", + " ax.set_xlim(0, 1.5)\n", + " ax.set_ylim(0, 1.5)\n", + " ax.set_title(\"TNK with Xopt's CNSGA\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T21:51:58.283280100Z", + "start_time": "2023-09-06T21:51:58.000279400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T16:00:04.287031Z", + "iopub.status.busy": "2024-09-13T16:00:04.286924Z", + "iopub.status.idle": "2024-09-13T16:00:04.428891Z", + "shell.execute_reply": "2024-09-13T16:00:04.428627Z" + } + }, + "outputs": [], + "source": [ + "plot_population(X)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Write the current population" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T21:51:58.316288Z", + "start_time": "2023-09-06T21:51:58.285309200Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T16:00:04.430764Z", + "iopub.status.busy": "2024-09-13T16:00:04.430654Z", + "iopub.status.idle": "2024-09-13T16:00:04.436574Z", + "shell.execute_reply": "2024-09-13T16:00:04.436346Z" + } + }, + "outputs": [], + "source": [ + "X.generator.write_population(\"test.csv\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# YAML method" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T21:51:58.373278300Z", + "start_time": "2023-09-06T21:51:58.316288Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T16:00:04.438007Z", + "iopub.status.busy": "2024-09-13T16:00:04.437902Z", + "iopub.status.idle": "2024-09-13T16:00:04.444599Z", + "shell.execute_reply": "2024-09-13T16:00:04.444366Z" + } + }, + "outputs": [], + "source": [ + "YAML = \"\"\"\n", + "max_evaluations: 6400\n", + "strict: False\n", + "generator:\n", + " name: cnsga\n", + " population_size: 32\n", + " population_file: test.csv\n", + " output_path: .\n", + "\n", + "evaluator:\n", + " function: xopt.resources.test_functions.tnk.evaluate_TNK\n", + " function_kwargs:\n", + " raise_probability: 0.1\n", + "\n", + "vocs:\n", + " variables:\n", + " x1: [0, 3.14159]\n", + " x2: [0, 3.14159]\n", + " objectives: {y1: MINIMIZE, y2: MINIMIZE}\n", + " constraints:\n", + " c1: [GREATER_THAN, 0]\n", + " c2: [LESS_THAN, 0.5]\n", + " constants: {a: dummy_constant}\n", + "\n", + "\"\"\"\n", + "\n", + "X = Xopt(YAML)\n", + "X" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "This will have loaded children from the population file. These will need to be re-evaluated." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T21:51:58.416310600Z", + "start_time": "2023-09-06T21:51:58.376279Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T16:00:04.445940Z", + "iopub.status.busy": "2024-09-13T16:00:04.445855Z", + "iopub.status.idle": "2024-09-13T16:00:04.447821Z", + "shell.execute_reply": "2024-09-13T16:00:04.447595Z" + } + }, + "outputs": [], + "source": [ + "len(X.generator._children)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T21:52:00.028438300Z", + "start_time": "2023-09-06T21:51:58.389282400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T16:00:04.449135Z", + "iopub.status.busy": "2024-09-13T16:00:04.449059Z", + "iopub.status.idle": "2024-09-13T16:00:12.513591Z", + "shell.execute_reply": "2024-09-13T16:00:12.513316Z" + } + }, + "outputs": [], + "source": [ + "%%time\n", + "X.run()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T21:52:00.248435500Z", + "start_time": "2023-09-06T21:52:00.026439100Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T16:00:12.514949Z", + "iopub.status.busy": "2024-09-13T16:00:12.514843Z", + "iopub.status.idle": "2024-09-13T16:00:12.676122Z", + "shell.execute_reply": "2024-09-13T16:00:12.675844Z" + } + }, + "outputs": [], + "source": [ + "plot_population(X)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T21:52:00.283467500Z", + "start_time": "2023-09-06T21:52:00.250437600Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T16:00:12.679960Z", + "iopub.status.busy": "2024-09-13T16:00:12.679838Z", + "iopub.status.idle": "2024-09-13T16:00:12.682027Z", + "shell.execute_reply": "2024-09-13T16:00:12.681797Z" + } + }, + "outputs": [], + "source": [ + "len(X.data)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Setting `output_path` will write .csv files for each population, as well as the offspring considered in each generation" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T21:52:00.284436600Z", + "start_time": "2023-09-06T21:52:00.264435700Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T16:00:12.683493Z", + "iopub.status.busy": "2024-09-13T16:00:12.683383Z", + "iopub.status.idle": "2024-09-13T16:00:12.685782Z", + "shell.execute_reply": "2024-09-13T16:00:12.685583Z" + } + }, + "outputs": [], + "source": [ + "pop_files = sorted(glob(\"cnsga_population*\"))\n", + "pop_files[:10]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T21:52:00.295436300Z", + "start_time": "2023-09-06T21:52:00.280436100Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T16:00:12.687091Z", + "iopub.status.busy": "2024-09-13T16:00:12.686989Z", + "iopub.status.idle": "2024-09-13T16:00:12.689402Z", + "shell.execute_reply": "2024-09-13T16:00:12.689121Z" + }, + "tags": [] + }, + "outputs": [], + "source": [ + "offspring_files = sorted(glob(\"cnsga_offspring*\"))\n", + "offspring_files[0:10]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T21:52:00.412434900Z", + "start_time": "2023-09-06T21:52:00.294436Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T16:00:12.690731Z", + "iopub.status.busy": "2024-09-13T16:00:12.690639Z", + "iopub.status.idle": "2024-09-13T16:00:12.756141Z", + "shell.execute_reply": "2024-09-13T16:00:12.755882Z" + } + }, + "outputs": [], + "source": [ + "pop_df = read_xopt_csv(pop_files[-1])\n", + "pop_df.plot.scatter(\"x1\", \"x2\", marker=\"o\", color=\"red\", alpha=1)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "tags": [] + }, + "source": [ + "Similarly, offsrping files can be loaded. This will load the last few:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T16:00:12.757854Z", + "iopub.status.busy": "2024-09-13T16:00:12.757734Z", + "iopub.status.idle": "2024-09-13T16:00:12.840341Z", + "shell.execute_reply": "2024-09-13T16:00:12.840075Z" + }, + "tags": [] + }, + "outputs": [], + "source": [ + "offspring_df = read_xopt_csv(*offspring_files[-10:])\n", + "offspring_df.plot.scatter(\"x1\", \"x2\", marker=\".\", color=\"black\", alpha=0.1)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Occationally there are duplicates in offspring" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T16:00:12.841961Z", + "iopub.status.busy": "2024-09-13T16:00:12.841848Z", + "iopub.status.idle": "2024-09-13T16:00:12.906879Z", + "shell.execute_reply": "2024-09-13T16:00:12.906594Z" + }, + "tags": [] + }, + "outputs": [], + "source": [ + "all_offspring = read_xopt_csv(*offspring_files)\n", + "len(all_offspring), len(all_offspring.drop_duplicates())" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T16:00:12.908464Z", + "iopub.status.busy": "2024-09-13T16:00:12.908347Z", + "iopub.status.idle": "2024-09-13T16:00:13.302556Z", + "shell.execute_reply": "2024-09-13T16:00:13.301941Z" + } + }, + "outputs": [], + "source": [ + "# Cleanup\n", + "!rm cnsga_population*\n", + "!rm cnsga_offspring*\n", + "!rm test.csv" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Examine generator" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T16:00:13.305396Z", + "iopub.status.busy": "2024-09-13T16:00:13.305190Z", + "iopub.status.idle": "2024-09-13T16:00:13.438995Z", + "shell.execute_reply": "2024-09-13T16:00:13.438672Z" + } + }, + "outputs": [], + "source": [ + "df = pd.DataFrame(X.generator.generate(1000))\n", + "\n", + "fig, ax = plt.subplots()\n", + "df.plot.scatter(\n", + " \"x1\", \"x2\", marker=\".\", color=\"green\", alpha=0.5, ax=ax, label=\"candidates\"\n", + ")\n", + "pop_df.plot.scatter(\n", + " \"x1\", \"x2\", marker=\"o\", color=\"red\", alpha=1, ax=ax, label=\"population\"\n", + ")\n", + "plt.legend()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Vectorized evaluation\n", + "\n", + "Some functions also allow vectorized inputs. This can often be very fast.\n", + "\n", + "However, vectorized evaluation has some restrictions. For example, the output dict cannot append additional arrays with odd lengths." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T16:00:13.440603Z", + "iopub.status.busy": "2024-09-13T16:00:13.440494Z", + "iopub.status.idle": "2024-09-13T16:00:13.442758Z", + "shell.execute_reply": "2024-09-13T16:00:13.442553Z" + } + }, + "outputs": [], + "source": [ + "# Notice that this returns `some_array`\n", + "evaluate_TNK({\"x1\": 1, \"x2\": 1})" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T16:00:13.444045Z", + "iopub.status.busy": "2024-09-13T16:00:13.443955Z", + "iopub.status.idle": "2024-09-13T16:00:13.445644Z", + "shell.execute_reply": "2024-09-13T16:00:13.445440Z" + } + }, + "outputs": [], + "source": [ + "# Here we make a version that does not have this\n", + "def evaluate_TNK2(*args, **kwargs):\n", + " outputs = evaluate_TNK(*args, **kwargs)\n", + " outputs.pop(\"some_array\")\n", + " return outputs" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T16:00:13.446869Z", + "iopub.status.busy": "2024-09-13T16:00:13.446796Z", + "iopub.status.idle": "2024-09-13T16:00:13.780954Z", + "shell.execute_reply": "2024-09-13T16:00:13.780631Z" + } + }, + "outputs": [], + "source": [ + "YAML = \"\"\"\n", + "max_evaluations: 6400\n", + "strict: False\n", + "generator:\n", + " name: cnsga\n", + " population_size: 32\n", + "\n", + "evaluator:\n", + " function: __main__.evaluate_TNK2\n", + " function_kwargs:\n", + " raise_probability: 0.1\n", + " vectorized: True\n", + " max_workers: 32\n", + "\n", + "vocs:\n", + " variables:\n", + " x1: [0, 3.14159]\n", + " x2: [0, 3.14159]\n", + " objectives: {y1: MINIMIZE, y2: MINIMIZE}\n", + " constraints:\n", + " c1: [GREATER_THAN, 0]\n", + " c2: [LESS_THAN, 0.5]\n", + " constants: {a: dummy_constant}\n", + "\n", + "\"\"\"\n", + "\n", + "\n", + "X2 = Xopt.from_yaml(YAML)\n", + "X2.evaluator.function = evaluate_TNK2\n", + "\n", + "X2.run()\n", + "\n", + "len(X2.data)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T16:00:13.782675Z", + "iopub.status.busy": "2024-09-13T16:00:13.782545Z", + "iopub.status.idle": "2024-09-13T16:00:13.945257Z", + "shell.execute_reply": "2024-09-13T16:00:13.945001Z" + }, + "tags": [] + }, + "outputs": [], + "source": [ + "plot_population(X)" + ] + } + ], + "metadata": { + "interpreter": { + "hash": "72034539424920dfb606fe3b820b3f27dca0cbf1c69938110810ec4641e275b1" + }, + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/ga/nsga2.ipynb b/docs/examples/ga/nsga2.ipynb new file mode 100644 index 0000000..9f64d63 --- /dev/null +++ b/docs/examples/ga/nsga2.ipynb @@ -0,0 +1,374 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# NSGA2 Generator\n", + "This notebook demonstrates the use of the generator `NSGA2Generator` which implements the NSGA-II algorithm from [1]. We show how to set up the optimizer object, use it to solve a test problem, and show off some of the generator's output features. Running this notebook will generate files in a temporary directory on your computer. These files will be cleaned up at the end." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import json\n", + "import logging\n", + "import matplotlib.pyplot as plt\n", + "import os\n", + "import pandas as pd\n", + "import shutil\n", + "import tempfile\n", + "\n", + "from xopt.generators.ga.nsga2 import (\n", + " NSGA2Generator,\n", + " PolynomialMutation,\n", + " SimulatedBinaryCrossover,\n", + ")\n", + "from xopt.resources.test_functions.zdt import construct_zdt\n", + "from xopt import Xopt, Evaluator, VOCS" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# The NSGA2Generator object emits logger messages\n", + "# Configure the logging module to output them to console\n", + "logging.basicConfig(\n", + " level=logging.INFO,\n", + " format=\"%(asctime)s - %(name)s - %(levelname)s - %(message)s\", # Format for log messages\n", + " datefmt=\"%Y-%m-%d %H:%M:%S\", # Date/time format\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Get the problem ZDT2 and create an Xopt evaluator\n", + "prob_vocs, prob_fun, _ = construct_zdt(30, 3)\n", + "ev = Evaluator(function=prob_fun)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Generator Setup and Use\n", + "First we create the `NSGA2Generator` object, demonstrate some of its settings, and then use it to solve the ZDT3 test problem." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Create the NSGA2 generator with default settings\n", + "generator = NSGA2Generator(\n", + " vocs=prob_vocs, # Must provide the problem's details\n", + ")\n", + "\n", + "# Let's demonstrate controlling the generator's hyperparameters and settings\n", + "generator = NSGA2Generator(\n", + " vocs=prob_vocs, # Must provide the problem's details\n", + " population_size=50, # How many individuals in a population\n", + " mutation_operator=PolynomialMutation(\n", + " pm=1 / 30, eta_m=20\n", + " ), # Can manually specify mutation operator and hyperparameters\n", + " crossover_operator=SimulatedBinaryCrossover(\n", + " delta_1=0.5, delta_2=0.5, eta_c=20\n", + " ), # Similarly can specify crossover manually\n", + " deduplicate_output=True, # Performs deduplication of candidate individuals. Ensure unique outputs from generator.\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Run the optimizer for a few generations. Notice log output printed below this cell\n", + "ev.max_workers = generator.population_size\n", + "X = Xopt(generator=generator, evaluator=ev, vocs=prob_vocs)\n", + "\n", + "for _ in range(3):\n", + " X.step()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Exploring Optimizer Output\n", + "We now take a look at the metadata associated with the optimizer run as well as its output." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "%%time\n", + "# Run for longer with log output turned off\n", + "for handler in logging.root.handlers[:]:\n", + " logging.root.removeHandler(handler)\n", + "\n", + "for _ in range(47):\n", + " X.step()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Inspect generator properties\n", + "print(\n", + " f\"Saw {generator.fevals} function evaluations\"\n", + ") # Number of function evaluations returned to generator\n", + "print(\n", + " f\"Completed {generator.n_generations} generations\"\n", + ") # Number of generations finished\n", + "print(\n", + " f\"Generated {generator.n_candidates} candidate solutions\"\n", + ") # Number of individuals generated" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# All evaluations are stored in the following Dataframe. Speific to this generator, a `xopt_parent_generation` and\n", + "# `xopt_candidate_idx` columns which indicate from which generation the indvidual's parents belong to as well as providing a\n", + "# unique index for indviduals.\n", + "#\n", + "# NOTE: The data DataFrame is not stored when serializing the generator. It must be saved on its own for later use.\n", + "generator.data.head()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Each population the optimizer has seen is stored by the unique indices of each individual.\n", + "print(generator.history_idx[-1][:16]) # Show the first few indices of last generation\n", + "\n", + "# If you have the data DataFrame you can extract all variables, objectives, constraints for each population\n", + "# Get a DataFrame of all information for the first population with every row being an individual\n", + "generator.data[\n", + " generator.data[\"xopt_candidate_idx\"].isin(generator.history_idx[0])\n", + "].head()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Using the population records we can plot the final generation's objective functions\n", + "final_pop = generator.data[\n", + " generator.data[\"xopt_candidate_idx\"].isin(generator.history_idx[-1])\n", + "]\n", + "plt.scatter(final_pop[\"f1\"], final_pop[\"f2\"])\n", + "plt.xlabel(\"f1\")\n", + "plt.ylabel(\"f2\")\n", + "plt.title(f\"ZDT3, Generation {generator.n_generations}\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# File Output from Generator\n", + "In this section, we will take a look at the files which can be automatically written by the optimizer. We will create a temporary directory and clean it up at the end of this notebook.\n", + "\n", + "The output files are the following.\n", + " - `data.csv`: All data evaluated during the optimization\n", + " - `vocs.txt`: The VOCS object so that the objectives, constraints, decision variables are retained alongside the data\n", + " - `populations.csv`: Each population is written here with a column `xopt_generation` to distinguish which generation the row belongs to\n", + " - `checkpoints`: This generator periodically saves its full state to timestamped files in this directory\n", + " - `log.txt`: Log output from the generator is recorded to this file\n", + "\n", + " Wile running each of the blocks, go ahead and open the temporary directory printed from the next cell and take a look at the files for yourself." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Setup our output directory\n", + "output_dir = tempfile.mkdtemp()\n", + "print(f'Will write data to \"{output_dir}\"')" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Set up a generator configured to output data\n", + "generator = NSGA2Generator(\n", + " vocs=prob_vocs,\n", + " output_dir=output_dir, # Where will we write data\n", + " checkpoint_freq=8, # Turn on checkpoints and set ow often (in terms of generations) we save the optimizer state\n", + " log_level=logging.DEBUG, # Set the level of log messages output to our log file\n", + ")\n", + "\n", + "# Run it for a couple of generations\n", + "ev.max_workers = generator.population_size\n", + "X = Xopt(generator=generator, evaluator=ev, vocs=prob_vocs)\n", + "for _ in range(32):\n", + " X.step()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Check out the generated files\n", + "print(f'\"{output_dir}\": {os.listdir(output_dir)}')\n", + "checkpoint_dir = os.path.join(output_dir, \"checkpoints\")\n", + "print(f'\"checkpoints\": {os.listdir(checkpoint_dir)}')" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# In the event data was already written to `output_dir` the generator will choose a new path with a numeric suffix\n", + "# to avoid overwriting anything.\n", + "X = Xopt(\n", + " generator=NSGA2Generator(vocs=prob_vocs, output_dir=output_dir),\n", + " evaluator=ev,\n", + " vocs=prob_vocs,\n", + ")\n", + "for _ in range(32):\n", + " X.step()\n", + "\n", + "# Compare the requested path and where the data ended up\n", + "print(f'Requested path: \"{output_dir}\"')\n", + "print(f'Path used: \"{X.generator.output_dir}\"')\n", + "\n", + "# Clean up the directory\n", + "X.generator.close_log_file()\n", + "shutil.rmtree(X.generator.output_dir)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Load all data back in\n", + "df = pd.read_csv(os.path.join(generator.output_dir, \"data.csv\"))\n", + "df.head()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Read the VOCS object back in. This can be used for data analysis / restarting optimizations\n", + "with open(os.path.join(generator.output_dir, \"vocs.txt\")) as f:\n", + " vocs_from_file = VOCS.from_dict(json.load(f))\n", + "\n", + "# Show the objectives\n", + "vocs_from_file.objectives" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Load the populations and get just the last population\n", + "df = pd.read_csv(os.path.join(generator.output_dir, \"populations.csv\"))\n", + "last_pop = df[df[\"xopt_generation\"] == df[\"xopt_generation\"].max()]\n", + "last_pop.head()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Reload the optimizer from its last checkpoint\n", + "# NOTE: the vocs object is not retained with the checkpoint and should be added as in the following code\n", + "last_checkpoint = os.path.join(checkpoint_dir, os.listdir(checkpoint_dir)[-1])\n", + "with open(last_checkpoint) as f:\n", + " restored_generator = NSGA2Generator.from_dict({\"vocs\": prob_vocs, **json.load(f)})\n", + "print(f\"From file: {restored_generator}\")\n", + "\n", + "# Demonstrate using the generator after loading (starting optimization from its last saved point)\n", + "X = Xopt(generator=restored_generator, evaluator=ev, vocs=prob_vocs)\n", + "for _ in range(32):\n", + " X.step()\n", + "print(f\"Further optimization: {restored_generator}\")\n", + "\n", + "# Clean up the output\n", + "X.generator.close_log_file()\n", + "shutil.rmtree(X.generator.output_dir)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Clean up the original output\n", + "generator.close_log_file()\n", + "shutil.rmtree(output_dir)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.13.2" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/docs/examples/gp_model_creation/model_creation.ipynb b/docs/examples/gp_model_creation/model_creation.ipynb new file mode 100644 index 0000000..8925636 --- /dev/null +++ b/docs/examples/gp_model_creation/model_creation.ipynb @@ -0,0 +1,259 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Building GP Models from Scratch\n", + "Sometimes it is useful to build GP models outside the context of BO for data\n", + "visualization and senativity measurements, ie. learned hyperparameters. Here we\n", + "demonstrate how to build models from data outside of generators.\n", + "\n", + "For this we use the 3D rosenbrock function test function." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2025-01-07T21:01:37.888221500Z", + "start_time": "2025-01-07T21:01:33.895927300Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:57.465196Z", + "iopub.status.busy": "2024-09-13T15:56:57.464798Z", + "iopub.status.idle": "2024-09-13T15:56:59.020677Z", + "shell.execute_reply": "2024-09-13T15:56:59.020398Z" + } + }, + "outputs": [], + "source": [ + "# set values if testing\n", + "import os\n", + "\n", + "from xopt import Xopt, Evaluator\n", + "from xopt.generators import RandomGenerator\n", + "from xopt.resources.test_functions.rosenbrock import (\n", + " evaluate_rosenbrock,\n", + " make_rosenbrock_vocs,\n", + ")\n", + "\n", + "from xopt.generators.bayesian.visualize import visualize_model\n", + "from xopt.generators.bayesian.models.standard import StandardModelConstructor\n", + "\n", + "# Ignore all warnings\n", + "import warnings\n", + "\n", + "warnings.filterwarnings(\"ignore\")\n", + "\n", + "\n", + "SMOKE_TEST = os.environ.get(\"SMOKE_TEST\")\n", + "NUM_MC_SAMPLES = 1 if SMOKE_TEST else 128\n", + "NUM_RESTARTS = 1 if SMOKE_TEST else 20\n", + "\n", + "# make rosenbrock function vocs in 3D\n", + "vocs = make_rosenbrock_vocs(3)\n", + "\n", + "# collect some data using random sampling\n", + "evaluator = Evaluator(function=evaluate_rosenbrock)\n", + "generator = RandomGenerator(vocs=vocs)\n", + "X = Xopt(generator=generator, evaluator=evaluator, vocs=vocs)\n", + "X.random_evaluate(15)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Create GP model based on the data" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2025-01-07T21:01:37.891750100Z", + "start_time": "2025-01-07T21:01:37.890225800Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:59.042358Z", + "iopub.status.busy": "2024-09-13T15:56:59.042170Z", + "iopub.status.idle": "2024-09-13T15:56:59.043905Z", + "shell.execute_reply": "2024-09-13T15:56:59.043681Z" + } + }, + "outputs": [], + "source": [ + "data = X.data" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2025-01-07T21:01:38.729744700Z", + "start_time": "2025-01-07T21:01:37.892751300Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:59.045209Z", + "iopub.status.busy": "2024-09-13T15:56:59.045127Z", + "iopub.status.idle": "2024-09-13T15:56:59.301614Z", + "shell.execute_reply": "2024-09-13T15:56:59.301336Z" + } + }, + "outputs": [], + "source": [ + "model_constructor = StandardModelConstructor()\n", + "\n", + "# here we build a model from vocs\n", + "model = model_constructor.build_model_from_vocs(vocs=vocs, data=data)\n", + "\n", + "# here we build a model from info (more flexible)\n", + "model = model_constructor.build_model(\n", + " input_names=[\"x0\", \"x1\", \"x2\"], outcome_names=[\"y\"], data=data\n", + ")\n", + "help(model_constructor.build_model)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Examine GP model hyperparameters\n", + "Here we look at the GP hyperparameters for the objective function (the first model).\n", + "Note: the hyperparameters here are in raw_units (due to contraints on parameter\n", + "values, ie. lengthscales > 0)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2025-01-07T21:01:38.736745Z", + "start_time": "2025-01-07T21:01:38.731745300Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:59.303297Z", + "iopub.status.busy": "2024-09-13T15:56:59.303134Z", + "iopub.status.idle": "2024-09-13T15:56:59.306355Z", + "shell.execute_reply": "2024-09-13T15:56:59.306053Z" + } + }, + "outputs": [], + "source": [ + "objective_model = model.models[vocs.output_names.index(\"y\")]\n", + "\n", + "# print raw hyperparameter values\n", + "for name, val in objective_model.named_parameters():\n", + " print(name, val)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2025-01-07T21:06:12.904773200Z", + "start_time": "2025-01-07T21:06:12.899686500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:59.307614Z", + "iopub.status.busy": "2024-09-13T15:56:59.307530Z", + "iopub.status.idle": "2024-09-13T15:56:59.310005Z", + "shell.execute_reply": "2024-09-13T15:56:59.309776Z" + } + }, + "outputs": [], + "source": [ + "# print real values - note that these are in normalized coordinates\n", + "print(\"prior mean:\", objective_model.mean_module.constant.data)\n", + "print(\"noise:\", objective_model.likelihood.noise_covar.noise.data)\n", + "print(\"lengthscales\", objective_model.covar_module.lengthscale.data)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2025-01-07T21:02:08.637731400Z", + "start_time": "2025-01-07T21:02:08.632699900Z" + } + }, + "outputs": [], + "source": [ + "objective_model" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Visualize model predictions" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:56:59.311380Z", + "iopub.status.busy": "2024-09-13T15:56:59.311290Z", + "iopub.status.idle": "2024-09-13T15:56:59.854969Z", + "shell.execute_reply": "2024-09-13T15:56:59.854557Z" + } + }, + "outputs": [], + "source": [ + "fig, ax = visualize_model(\n", + " model, vocs, data, variable_names=[\"x0\", \"x1\"], reference_point={\"x2\": 0.0}\n", + ")" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/multi_objective_bayes_opt/mggpo.ipynb b/docs/examples/multi_objective_bayes_opt/mggpo.ipynb new file mode 100644 index 0000000..e5c10f0 --- /dev/null +++ b/docs/examples/multi_objective_bayes_opt/mggpo.ipynb @@ -0,0 +1,308 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "# Multi-objective Bayesian Optimization\n", + "\n", + "\n", + "TNK function\n", + "$n=2$ variables:\n", + "$x_i \\in [0, \\pi], i=1,2$\n", + "\n", + "Objectives:\n", + "- $f_i(x) = x_i$\n", + "\n", + "Constraints:\n", + "- $g_1(x) = -x_1^2 -x_2^2 + 1 + 0.1 \\cos\\left(16 \\arctan \\frac{x_1}{x_2}\\right) \\le 0$\n", + "- $g_2(x) = (x_1 - 1/2)^2 + (x_2-1/2)^2 \\le 0.5$" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-08-02T21:09:04.147494200Z", + "start_time": "2023-08-02T21:09:01.121464100Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:25.142407Z", + "iopub.status.busy": "2024-09-13T15:59:25.141916Z", + "iopub.status.idle": "2024-09-13T15:59:26.865350Z", + "shell.execute_reply": "2024-09-13T15:59:26.865058Z" + } + }, + "outputs": [], + "source": [ + "# set values if testing\n", + "import os\n", + "\n", + "from copy import deepcopy\n", + "\n", + "import pandas as pd\n", + "import numpy as np\n", + "import torch\n", + "\n", + "from xopt import Xopt, Evaluator\n", + "from xopt.generators.bayesian.mggpo import MGGPOGenerator\n", + "from xopt.resources.test_functions.tnk import evaluate_TNK, tnk_vocs\n", + "\n", + "from xopt.generators.bayesian.objectives import feasibility\n", + "\n", + "from matplotlib import pyplot as plt\n", + "\n", + "# Ignore all warnings\n", + "import warnings\n", + "\n", + "warnings.filterwarnings(\"ignore\")\n", + "\n", + "SMOKE_TEST = os.environ.get(\"SMOKE_TEST\")\n", + "N_MC_SAMPLES = 1 if SMOKE_TEST else 128\n", + "NUM_RESTARTS = 1 if SMOKE_TEST else 20\n", + "\n", + "evaluator = Evaluator(function=evaluate_TNK)\n", + "evaluator.max_workers = 10\n", + "\n", + "# test check options\n", + "vocs = deepcopy(tnk_vocs)\n", + "gen = MGGPOGenerator(vocs=vocs, reference_point={\"y1\": 1.5, \"y2\": 1.5})\n", + "gen.n_monte_carlo_samples = N_MC_SAMPLES\n", + "gen.numerical_optimizer.n_restarts = NUM_RESTARTS\n", + "X = Xopt(evaluator=evaluator, generator=gen, vocs=vocs)\n", + "X.evaluate_data(pd.DataFrame({\"x1\": [1.0, 0.75], \"x2\": [0.75, 1.0]}))\n", + "\n", + "X" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-08-02T21:09:13.737232800Z", + "start_time": "2023-08-02T21:09:04.149492900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:26.886511Z", + "iopub.status.busy": "2024-09-13T15:59:26.886313Z", + "iopub.status.idle": "2024-09-13T15:59:30.099103Z", + "shell.execute_reply": "2024-09-13T15:59:30.098791Z" + } + }, + "outputs": [], + "source": [ + "for i in range(10):\n", + " print(i)\n", + " X.step()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-08-02T21:09:13.768374600Z", + "start_time": "2023-08-02T21:09:13.735233200Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:30.100858Z", + "iopub.status.busy": "2024-09-13T15:59:30.100700Z", + "iopub.status.idle": "2024-09-13T15:59:30.106910Z", + "shell.execute_reply": "2024-09-13T15:59:30.106694Z" + } + }, + "outputs": [], + "source": [ + "X.generator.data" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## plot results\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-08-02T21:09:14.288220800Z", + "start_time": "2023-08-02T21:09:13.765373900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:30.108409Z", + "iopub.status.busy": "2024-09-13T15:59:30.108317Z", + "iopub.status.idle": "2024-09-13T15:59:30.185242Z", + "shell.execute_reply": "2024-09-13T15:59:30.184988Z" + } + }, + "outputs": [], + "source": [ + "fig, ax = plt.subplots()\n", + "\n", + "theta = np.linspace(0, np.pi / 2)\n", + "r = np.sqrt(1 + 0.1 * np.cos(16 * theta))\n", + "x_1 = r * np.sin(theta)\n", + "x_2_lower = r * np.cos(theta)\n", + "x_2_upper = (0.5 - (x_1 - 0.5) ** 2) ** 0.5 + 0.5\n", + "\n", + "z = np.zeros_like(x_1)\n", + "\n", + "# ax2.plot(x_1, x_2_lower,'r')\n", + "ax.fill_between(x_1, z, x_2_lower, fc=\"white\")\n", + "circle = plt.Circle(\n", + " (0.5, 0.5), 0.5**0.5, color=\"r\", alpha=0.25, zorder=0, label=\"Valid Region\"\n", + ")\n", + "ax.add_patch(circle)\n", + "history = pd.concat(\n", + " [X.data, tnk_vocs.feasibility_data(X.data)], axis=1, ignore_index=False\n", + ")\n", + "\n", + "ax.plot(*history[[\"x1\", \"x2\"]][history[\"feasible\"]].to_numpy().T, \".C1\")\n", + "ax.plot(*history[[\"x1\", \"x2\"]][~history[\"feasible\"]].to_numpy().T, \".C2\")\n", + "\n", + "ax.set_xlim(0, 3.14)\n", + "ax.set_ylim(0, 3.14)\n", + "ax.set_xlabel(\"x1\")\n", + "ax.set_ylabel(\"x2\")\n", + "ax.set_aspect(\"equal\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "start_time": "2023-08-02T21:09:14.297221Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:30.186678Z", + "iopub.status.busy": "2024-09-13T15:59:30.186581Z", + "iopub.status.idle": "2024-09-13T15:59:31.128132Z", + "shell.execute_reply": "2024-09-13T15:59:31.127827Z" + }, + "is_executing": true + }, + "outputs": [], + "source": [ + "# plot model predictions\n", + "\n", + "data = X.data\n", + "\n", + "bounds = X.generator.vocs.bounds\n", + "model = X.generator.train_model(X.generator.data)\n", + "\n", + "# create mesh\n", + "n = 50\n", + "x = torch.linspace(*bounds.T[0], n)\n", + "y = torch.linspace(*bounds.T[1], n)\n", + "xx, yy = torch.meshgrid(x, y)\n", + "pts = torch.hstack([ele.reshape(-1, 1) for ele in (xx, yy)]).double()\n", + "\n", + "xx, yy = xx.numpy(), yy.numpy()\n", + "\n", + "outputs = X.generator.vocs.output_names\n", + "with torch.no_grad():\n", + " post = model.posterior(pts)\n", + "\n", + " for i in range(len(vocs.output_names)):\n", + " mean = post.mean[..., i]\n", + " fig, ax = plt.subplots()\n", + " ax.plot(*data[[\"x1\", \"x2\"]].to_numpy().T, \"+C1\")\n", + " c = ax.pcolor(\n", + " xx, yy, mean.squeeze().reshape(n, n), cmap=\"seismic\", vmin=-10.0, vmax=10.0\n", + " )\n", + " fig.colorbar(c)\n", + " ax.set_title(f\"Posterior mean: {outputs[i]}\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:59:31.129712Z", + "iopub.status.busy": "2024-09-13T15:59:31.129588Z", + "iopub.status.idle": "2024-09-13T15:59:32.372484Z", + "shell.execute_reply": "2024-09-13T15:59:32.372224Z" + }, + "is_executing": true + }, + "outputs": [], + "source": [ + "# plot the acquisition function\n", + "bounds = X.generator.vocs.bounds\n", + "model = X.generator.model\n", + "\n", + "# create mesh\n", + "n = 25\n", + "x = torch.linspace(*bounds.T[0], n)\n", + "y = torch.linspace(*bounds.T[1], n)\n", + "xx, yy = torch.meshgrid(x, y)\n", + "pts = torch.hstack([ele.reshape(-1, 1) for ele in (xx, yy)]).double()\n", + "\n", + "xx, yy = xx.numpy(), yy.numpy()\n", + "\n", + "acq_func = X.generator.get_acquisition(model)\n", + "with torch.no_grad():\n", + " acq_pts = pts.unsqueeze(1)\n", + " acq = acq_func(acq_pts)\n", + "\n", + " fig, ax = plt.subplots()\n", + " c = ax.pcolor(xx, yy, acq.reshape(n, n), cmap=\"Blues\")\n", + " fig.colorbar(c)\n", + " ax.set_title(\"Acquisition function\")\n", + "\n", + " ax.plot(*history[[\"x1\", \"x2\"]][history[\"feasible\"]].to_numpy().T, \".C1\")\n", + " ax.plot(*history[[\"x1\", \"x2\"]][~history[\"feasible\"]].to_numpy().T, \".C2\")\n", + "\n", + " ax.plot(*history[[\"x1\", \"x2\"]].to_numpy()[-1].T, \"+\")\n", + "\n", + " feas = feasibility(pts.unsqueeze(1), model, tnk_vocs).flatten()\n", + "\n", + " fig2, ax2 = plt.subplots()\n", + " c = ax2.pcolor(xx, yy, feas.reshape(n, n))\n", + " fig2.colorbar(c)\n", + " ax2.set_title(\"Feasible Region\")\n", + "\n", + "candidate = pd.DataFrame(X.generator.generate(1), index=[0])\n", + "print(candidate[[\"x1\", \"x2\"]].to_numpy())\n", + "ax.plot(*candidate[[\"x1\", \"x2\"]].to_numpy()[0], \"o\")" + ] + } + ], + "metadata": { + "interpreter": { + "hash": "72034539424920dfb606fe3b820b3f27dca0cbf1c69938110810ec4641e275b1" + }, + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/multi_objective_bayes_opt/mobo.ipynb b/docs/examples/multi_objective_bayes_opt/mobo.ipynb new file mode 100644 index 0000000..ba33f58 --- /dev/null +++ b/docs/examples/multi_objective_bayes_opt/mobo.ipynb @@ -0,0 +1,232 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "# Multi-objective Bayesian Optimization\n", + "\n", + "\n", + "TNK function\n", + "$n=2$ variables:\n", + "$x_i \\in [0, \\pi], i=1,2$\n", + "\n", + "Objectives:\n", + "- $f_i(x) = x_i$\n", + "\n", + "Constraints:\n", + "- $g_1(x) = -x_1^2 -x_2^2 + 1 + 0.1 \\cos\\left(16 \\arctan \\frac{x_1}{x_2}\\right) \\le 0$\n", + "- $g_2(x) = (x_1 - 1/2)^2 + (x_2-1/2)^2 \\le 0.5$" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:57:02.030381Z", + "iopub.status.busy": "2024-09-13T15:57:02.029788Z", + "iopub.status.idle": "2024-09-13T15:57:03.730252Z", + "shell.execute_reply": "2024-09-13T15:57:03.729920Z" + } + }, + "outputs": [], + "source": [ + "# set values if testing\n", + "import os\n", + "\n", + "import pandas as pd\n", + "import numpy as np\n", + "\n", + "from xopt import Xopt, Evaluator\n", + "from xopt.generators.bayesian import MOBOGenerator\n", + "from xopt.resources.test_functions.tnk import evaluate_TNK, tnk_vocs\n", + "\n", + "import matplotlib.pyplot as plt\n", + "\n", + "# Ignore all warnings\n", + "import warnings\n", + "\n", + "warnings.filterwarnings(\"ignore\")\n", + "\n", + "SMOKE_TEST = os.environ.get(\"SMOKE_TEST\")\n", + "N_MC_SAMPLES = 1 if SMOKE_TEST else 128\n", + "NUM_RESTARTS = 1 if SMOKE_TEST else 20\n", + "N_STEPS = 1 if SMOKE_TEST else 30\n", + "\n", + "evaluator = Evaluator(function=evaluate_TNK)\n", + "print(tnk_vocs.dict())" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:57:03.751516Z", + "iopub.status.busy": "2024-09-13T15:57:03.751311Z", + "iopub.status.idle": "2024-09-13T15:57:29.768361Z", + "shell.execute_reply": "2024-09-13T15:57:29.768054Z" + } + }, + "outputs": [], + "source": [ + "generator = MOBOGenerator(vocs=tnk_vocs, reference_point={\"y1\": 1.5, \"y2\": 1.5})\n", + "generator.n_monte_carlo_samples = N_MC_SAMPLES\n", + "generator.numerical_optimizer.n_restarts = NUM_RESTARTS\n", + "\n", + "X = Xopt(generator=generator, evaluator=evaluator, vocs=tnk_vocs)\n", + "X.evaluate_data(pd.DataFrame({\"x1\": [1.0, 0.75], \"x2\": [0.75, 1.0]}))\n", + "\n", + "for i in range(N_STEPS):\n", + " print(i)\n", + " X.step()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:57:29.770136Z", + "iopub.status.busy": "2024-09-13T15:57:29.769968Z", + "iopub.status.idle": "2024-09-13T15:57:29.778804Z", + "shell.execute_reply": "2024-09-13T15:57:29.778491Z" + } + }, + "outputs": [], + "source": [ + "X.generator.data" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## plot results\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:57:29.780374Z", + "iopub.status.busy": "2024-09-13T15:57:29.780251Z", + "iopub.status.idle": "2024-09-13T15:57:29.856479Z", + "shell.execute_reply": "2024-09-13T15:57:29.856193Z" + } + }, + "outputs": [], + "source": [ + "fig, ax = plt.subplots()\n", + "\n", + "theta = np.linspace(0, np.pi / 2)\n", + "r = np.sqrt(1 + 0.1 * np.cos(16 * theta))\n", + "x_1 = r * np.sin(theta)\n", + "x_2_lower = r * np.cos(theta)\n", + "x_2_upper = (0.5 - (x_1 - 0.5) ** 2) ** 0.5 + 0.5\n", + "\n", + "z = np.zeros_like(x_1)\n", + "\n", + "# ax2.plot(x_1, x_2_lower,'r')\n", + "ax.fill_between(x_1, z, x_2_lower, fc=\"white\")\n", + "circle = plt.Circle(\n", + " (0.5, 0.5), 0.5**0.5, color=\"r\", alpha=0.25, zorder=0, label=\"Valid Region\"\n", + ")\n", + "ax.add_patch(circle)\n", + "history = pd.concat(\n", + " [X.data, tnk_vocs.feasibility_data(X.data)], axis=1, ignore_index=False\n", + ")\n", + "\n", + "\n", + "ax.plot(*history[[\"x1\", \"x2\"]][history[\"feasible\"]].to_numpy().T, \".C1\")\n", + "ax.plot(*history[[\"x1\", \"x2\"]][~history[\"feasible\"]].to_numpy().T, \".C2\")\n", + "\n", + "ax.set_xlim(0, 3.14)\n", + "ax.set_ylim(0, 3.14)\n", + "ax.set_xlabel(\"x1\")\n", + "ax.set_ylabel(\"x2\")\n", + "ax.set_aspect(\"equal\")" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "### Plot path through input space" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:57:29.858123Z", + "iopub.status.busy": "2024-09-13T15:57:29.857992Z", + "iopub.status.idle": "2024-09-13T15:57:29.929182Z", + "shell.execute_reply": "2024-09-13T15:57:29.928898Z" + } + }, + "outputs": [], + "source": [ + "ax = history.plot(\"x1\", \"x2\")\n", + "ax.set_ylim(0, 3.14)\n", + "ax.set_xlim(0, 3.14)\n", + "ax.set_aspect(\"equal\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:57:29.930805Z", + "iopub.status.busy": "2024-09-13T15:57:29.930596Z", + "iopub.status.idle": "2024-09-13T15:57:37.626954Z", + "shell.execute_reply": "2024-09-13T15:57:37.626631Z" + } + }, + "outputs": [], + "source": [ + "## visualize model\n", + "X.generator.visualize_model()" + ] + } + ], + "metadata": { + "interpreter": { + "hash": "72034539424920dfb606fe3b820b3f27dca0cbf1c69938110810ec4641e275b1" + }, + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/multi_objective_bayes_opt/mobo_from_yaml.ipynb b/docs/examples/multi_objective_bayes_opt/mobo_from_yaml.ipynb new file mode 100644 index 0000000..8d986eb --- /dev/null +++ b/docs/examples/multi_objective_bayes_opt/mobo_from_yaml.ipynb @@ -0,0 +1,243 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "# Multi-objective Bayesian Optimization\n", + "\n", + "\n", + "TNK function\n", + "$n=2$ variables:\n", + "$x_i \\in [0, \\pi], i=1,2$\n", + "\n", + "Objectives:\n", + "- $f_i(x) = x_i$\n", + "\n", + "Constraints:\n", + "- $g_1(x) = -x_1^2 -x_2^2 + 1 + 0.1 \\cos\\left(16 \\arctan \\frac{x_1}{x_2}\\right) \\le 0$\n", + "- $g_2(x) = (x_1 - 1/2)^2 + (x_2-1/2)^2 \\le 0.5$" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:58:42.418134Z", + "iopub.status.busy": "2024-09-13T15:58:42.417864Z", + "iopub.status.idle": "2024-09-13T15:58:44.142616Z", + "shell.execute_reply": "2024-09-13T15:58:44.142320Z" + } + }, + "outputs": [], + "source": [ + "import os\n", + "from xopt import Xopt\n", + "import matplotlib.pyplot as plt\n", + "import numpy as np\n", + "import pandas as pd\n", + "\n", + "\n", + "# Ignore all warnings\n", + "import warnings\n", + "\n", + "warnings.filterwarnings(\"ignore\")\n", + "\n", + "SMOKE_TEST = os.environ.get(\"SMOKE_TEST\")\n", + "NUM_STEPS = 2 if SMOKE_TEST else 50\n", + "\n", + "YAML = \"\"\"\n", + "generator:\n", + " name: mobo\n", + " reference_point: {y1: 1.5, y2: 1.5}\n", + "\n", + "evaluator:\n", + " function: xopt.resources.test_functions.tnk.evaluate_TNK\n", + "\n", + "vocs:\n", + " variables:\n", + " x1: [0, 3.14159]\n", + " x2: [0, 3.14159]\n", + " objectives: {y1: MINIMIZE, y2: MINIMIZE}\n", + " constraints:\n", + " c1: [GREATER_THAN, 0]\n", + " c2: [LESS_THAN, 0.5]\n", + " constants: {a: dummy_constant}\n", + "\n", + "\"\"\"" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:58:44.144448Z", + "iopub.status.busy": "2024-09-13T15:58:44.144296Z", + "iopub.status.idle": "2024-09-13T15:59:19.006532Z", + "shell.execute_reply": "2024-09-13T15:59:19.006230Z" + } + }, + "outputs": [], + "source": [ + "X = Xopt.from_yaml(YAML)\n", + "\n", + "# for testing purposes only\n", + "if SMOKE_TEST:\n", + " X.generator.numerical_optimizer.n_restarts = 1\n", + " X.generator.n_monte_carlo_samples = 1\n", + "\n", + "X.random_evaluate(5)\n", + "for i in range(NUM_STEPS):\n", + " print(i)\n", + " X.step()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:59:19.008255Z", + "iopub.status.busy": "2024-09-13T15:59:19.008111Z", + "iopub.status.idle": "2024-09-13T15:59:19.018656Z", + "shell.execute_reply": "2024-09-13T15:59:19.018378Z" + } + }, + "outputs": [], + "source": [ + "X.generator.data" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## plot results\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:59:19.020019Z", + "iopub.status.busy": "2024-09-13T15:59:19.019929Z", + "iopub.status.idle": "2024-09-13T15:59:19.094493Z", + "shell.execute_reply": "2024-09-13T15:59:19.094211Z" + } + }, + "outputs": [], + "source": [ + "fig, ax = plt.subplots()\n", + "\n", + "theta = np.linspace(0, np.pi / 2)\n", + "r = np.sqrt(1 + 0.1 * np.cos(16 * theta))\n", + "x_1 = r * np.sin(theta)\n", + "x_2_lower = r * np.cos(theta)\n", + "x_2_upper = (0.5 - (x_1 - 0.5) ** 2) ** 0.5 + 0.5\n", + "\n", + "z = np.zeros_like(x_1)\n", + "\n", + "# ax2.plot(x_1, x_2_lower,'r')\n", + "ax.fill_between(x_1, z, x_2_lower, fc=\"white\")\n", + "circle = plt.Circle(\n", + " (0.5, 0.5), 0.5**0.5, color=\"r\", alpha=0.25, zorder=0, label=\"Valid Region\"\n", + ")\n", + "ax.add_patch(circle)\n", + "history = pd.concat(\n", + " [X.data, X.vocs.feasibility_data(X.data)], axis=1, ignore_index=False\n", + ")\n", + "\n", + "\n", + "ax.plot(*history[[\"x1\", \"x2\"]][history[\"feasible\"]].to_numpy().T, \".C1\")\n", + "ax.plot(*history[[\"x1\", \"x2\"]][~history[\"feasible\"]].to_numpy().T, \".C2\")\n", + "\n", + "ax.set_xlim(0, 3.14)\n", + "ax.set_ylim(0, 3.14)\n", + "ax.set_xlabel(\"x1\")\n", + "ax.set_ylabel(\"x2\")\n", + "ax.set_aspect(\"equal\")" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "### Plot path through input space" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:59:19.096122Z", + "iopub.status.busy": "2024-09-13T15:59:19.096008Z", + "iopub.status.idle": "2024-09-13T15:59:19.165547Z", + "shell.execute_reply": "2024-09-13T15:59:19.165289Z" + } + }, + "outputs": [], + "source": [ + "ax = history.plot(\"x1\", \"x2\")\n", + "ax.set_ylim(0, 3.14)\n", + "ax.set_xlim(0, 3.14)\n", + "ax.set_aspect(\"equal\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:59:19.167032Z", + "iopub.status.busy": "2024-09-13T15:59:19.166920Z", + "iopub.status.idle": "2024-09-13T15:59:22.869490Z", + "shell.execute_reply": "2024-09-13T15:59:22.869219Z" + } + }, + "outputs": [], + "source": [ + "## visualize model\n", + "X.generator.visualize_model()" + ] + } + ], + "metadata": { + "interpreter": { + "hash": "72034539424920dfb606fe3b820b3f27dca0cbf1c69938110810ec4641e275b1" + }, + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/multi_objective_bayes_opt/multi_fidelity_mobo.ipynb b/docs/examples/multi_objective_bayes_opt/multi_fidelity_mobo.ipynb new file mode 100644 index 0000000..43c564a --- /dev/null +++ b/docs/examples/multi_objective_bayes_opt/multi_fidelity_mobo.ipynb @@ -0,0 +1,430 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Multi-fidelity Multi-objective Bayesian Optimization\n", + "\n", + "Here we attempt to solve for the constrained Pareto front of the TNK multi-objective\n", + "optimization problem using Multi-Fidelity Multi-Objective Bayesian optimization. For\n", + "simplicity we assume that the objective and constraint functions at lower fidelities is\n", + "exactly equal to the functions at higher fidelities (this is obviously not a\n", + "requirement, although for the best results lower fidelity calculations should\n", + "correlate with higher fidelity ones). The algorithm should learn this relationship\n", + "and use information gathered at lower fidelities to gather samples to improve the\n", + "hypervolume of the Pareto front at the maximum fidelity.\n", + "\n", + "TNK function\n", + "$n=2$ variables:\n", + "$x_i \\in [0, \\pi], i=1,2$\n", + "\n", + "Objectives:\n", + "- $f_i(x) = x_i$\n", + "\n", + "Constraints:\n", + "- $g_1(x) = -x_1^2 -x_2^2 + 1 + 0.1 \\cos\\left(16 \\arctan \\frac{x_1}{x_2}\\right) \\le 0$\n", + "- $g_2(x) = (x_1 - 1/2)^2 + (x_2-1/2)^2 \\le 0.5$" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-20T14:37:08.616050600Z", + "start_time": "2023-09-20T14:37:04.101720300Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:57:40.581721Z", + "iopub.status.busy": "2024-09-13T15:57:40.581427Z", + "iopub.status.idle": "2024-09-13T15:57:42.766030Z", + "shell.execute_reply": "2024-09-13T15:57:42.765648Z" + } + }, + "outputs": [], + "source": [ + "# set values if testing\n", + "import os\n", + "from copy import deepcopy\n", + "\n", + "import pandas as pd\n", + "import numpy as np\n", + "import torch\n", + "\n", + "from xopt import Xopt, Evaluator\n", + "from xopt.generators.bayesian import MultiFidelityGenerator\n", + "from xopt.resources.test_functions.tnk import evaluate_TNK, tnk_vocs\n", + "\n", + "import matplotlib.pyplot as plt\n", + "\n", + "# Ignore all warnings\n", + "import warnings\n", + "\n", + "warnings.filterwarnings(\"ignore\")\n", + "\n", + "SMOKE_TEST = os.environ.get(\"SMOKE_TEST\")\n", + "N_MC_SAMPLES = 1 if SMOKE_TEST else 128\n", + "NUM_RESTARTS = 1 if SMOKE_TEST else 20\n", + "BUDGET = 0.02 if SMOKE_TEST else 10\n", + "\n", + "evaluator = Evaluator(function=evaluate_TNK)\n", + "print(tnk_vocs.dict())" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Set up the Multi-Fidelity Multi-objective optimization algorithm\n", + "Here we create the Multi-Fidelity generator object which can solve both single and\n", + "multi-objective optimization problems depending on the number of objectives in VOCS.\n", + "We specify a cost function as a function of fidelity parameter $s=[0,1]$ as $C(s) =\n", + "s^{3.5}$ as an example from a real life multi-fidelity simulation problem." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-20T14:37:08.660042Z", + "start_time": "2023-09-20T14:37:08.617041800Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:57:42.791139Z", + "iopub.status.busy": "2024-09-13T15:57:42.790899Z", + "iopub.status.idle": "2024-09-13T15:57:42.802241Z", + "shell.execute_reply": "2024-09-13T15:57:42.801931Z" + } + }, + "outputs": [], + "source": [ + "my_vocs = deepcopy(tnk_vocs)\n", + "my_vocs.constraints = {}\n", + "generator = MultiFidelityGenerator(vocs=my_vocs, reference_point={\"y1\": 1.5, \"y2\": 1.5})\n", + "\n", + "# set cost function according to approximate scaling of laser plasma accelerator\n", + "# problem, see https://journals.aps.org/prresearch/abstract/10.1103/PhysRevResearch.5.013063\n", + "generator.cost_function = lambda s: s**3.5\n", + "generator.numerical_optimizer.n_restarts = NUM_RESTARTS\n", + "generator.n_monte_carlo_samples = N_MC_SAMPLES\n", + "\n", + "X = Xopt(generator=generator, evaluator=evaluator, vocs=my_vocs)\n", + "\n", + "# evaluate at some explicit initial points\n", + "X.evaluate_data(pd.DataFrame({\"x1\": [1.0, 0.75], \"x2\": [0.75, 1.0], \"s\": [0.0, 0.1]}))\n", + "\n", + "X" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Run optimization routine\n", + "Instead of ending the optimization routine after an explict number of samples we end\n", + "optimization once a given optimization budget has been exceeded. WARNING: This will\n", + "slightly exceed the given budget" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-20T14:37:14.657062800Z", + "start_time": "2023-09-20T14:37:08.648042200Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:57:42.803987Z", + "iopub.status.busy": "2024-09-13T15:57:42.803801Z", + "iopub.status.idle": "2024-09-13T15:58:35.292838Z", + "shell.execute_reply": "2024-09-13T15:58:35.292503Z" + } + }, + "outputs": [], + "source": [ + "budget = BUDGET\n", + "while X.generator.calculate_total_cost() < budget:\n", + " X.step()\n", + " print(\n", + " f\"n_samples: {len(X.data)} \"\n", + " f\"budget used: {X.generator.calculate_total_cost():.4} \"\n", + " f\"hypervolume: {X.generator.calculate_hypervolume():.4}\"\n", + " )" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Show results" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-20T14:37:14.684015600Z", + "start_time": "2023-09-20T14:37:14.647063400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:58:35.294458Z", + "iopub.status.busy": "2024-09-13T15:58:35.294286Z", + "iopub.status.idle": "2024-09-13T15:58:35.304159Z", + "shell.execute_reply": "2024-09-13T15:58:35.303906Z" + } + }, + "outputs": [], + "source": [ + "X.data" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Plot results\n", + "Here we plot the resulting observations in input space, colored by feasibility\n", + "(neglecting the fact that\n", + "these data points are at varying fidelities).\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-20T14:37:15.292777300Z", + "start_time": "2023-09-20T14:37:14.679967200Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:58:35.305628Z", + "iopub.status.busy": "2024-09-13T15:58:35.305543Z", + "iopub.status.idle": "2024-09-13T15:58:35.380005Z", + "shell.execute_reply": "2024-09-13T15:58:35.379735Z" + } + }, + "outputs": [], + "source": [ + "fig, ax = plt.subplots()\n", + "\n", + "theta = np.linspace(0, np.pi / 2)\n", + "r = np.sqrt(1 + 0.1 * np.cos(16 * theta))\n", + "x_1 = r * np.sin(theta)\n", + "x_2_lower = r * np.cos(theta)\n", + "x_2_upper = (0.5 - (x_1 - 0.5) ** 2) ** 0.5 + 0.5\n", + "\n", + "z = np.zeros_like(x_1)\n", + "\n", + "# ax2.plot(x_1, x_2_lower,'r')\n", + "ax.fill_between(x_1, z, x_2_lower, fc=\"white\")\n", + "circle = plt.Circle(\n", + " (0.5, 0.5), 0.5**0.5, color=\"r\", alpha=0.25, zorder=0, label=\"Valid Region\"\n", + ")\n", + "ax.add_patch(circle)\n", + "history = pd.concat(\n", + " [X.data, tnk_vocs.feasibility_data(X.data)], axis=1, ignore_index=False\n", + ")\n", + "\n", + "ax.plot(*history[[\"x1\", \"x2\"]][history[\"feasible\"]].to_numpy().T, \".C1\")\n", + "ax.plot(*history[[\"x1\", \"x2\"]][~history[\"feasible\"]].to_numpy().T, \".C2\")\n", + "\n", + "ax.set_xlim(0, 3.14)\n", + "ax.set_ylim(0, 3.14)\n", + "ax.set_xlabel(\"x1\")\n", + "ax.set_ylabel(\"x2\")\n", + "ax.set_aspect(\"equal\")" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "### Plot path through input space" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-20T14:37:15.607777300Z", + "start_time": "2023-09-20T14:37:15.288777300Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:58:35.381462Z", + "iopub.status.busy": "2024-09-13T15:58:35.381358Z", + "iopub.status.idle": "2024-09-13T15:58:35.609159Z", + "shell.execute_reply": "2024-09-13T15:58:35.608874Z" + } + }, + "outputs": [], + "source": [ + "ax = history.hist([\"x1\", \"x2\", \"s\"], bins=20)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-20T14:37:15.768777Z", + "start_time": "2023-09-20T14:37:15.606777300Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:58:35.610675Z", + "iopub.status.busy": "2024-09-13T15:58:35.610566Z", + "iopub.status.idle": "2024-09-13T15:58:35.700614Z", + "shell.execute_reply": "2024-09-13T15:58:35.700341Z" + } + }, + "outputs": [], + "source": [ + "history.plot(y=[\"x1\", \"x2\", \"s\"])" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Plot the acqusisition function\n", + "Here we plot the acquisition function at a small set of fidelities $[0, 0.5, 1.0]$." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-20T14:37:45.334189800Z", + "start_time": "2023-09-20T14:37:41.203201700Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:58:35.702504Z", + "iopub.status.busy": "2024-09-13T15:58:35.702420Z", + "iopub.status.idle": "2024-09-13T15:58:40.147848Z", + "shell.execute_reply": "2024-09-13T15:58:40.147599Z" + } + }, + "outputs": [], + "source": [ + "# plot the acquisition function\n", + "\n", + "bounds = X.generator.vocs.bounds\n", + "model = X.generator.model\n", + "\n", + "# create mesh over non-fidelity parameters\n", + "n = 50\n", + "x = torch.linspace(*bounds.T[1], n)\n", + "y = torch.linspace(*bounds.T[2], n)\n", + "xx, yy = torch.meshgrid(x, y)\n", + "\n", + "# plot function(s) at a single fidelity parameter\n", + "fidelities = [0.0, 0.5, 1.0]\n", + "for fidelity in fidelities:\n", + " pts = torch.hstack([ele.reshape(-1, 1) for ele in (xx, yy)]).double()\n", + " pts = torch.cat((torch.ones(pts.shape[0], 1) * fidelity, pts), dim=-1)\n", + "\n", + " acq_func = X.generator.get_acquisition(model)\n", + " with torch.no_grad():\n", + " acq_pts = pts.unsqueeze(1)\n", + " acq = acq_func(acq_pts)\n", + "\n", + " fig, ax = plt.subplots()\n", + "\n", + " xxn, yyn = xx.numpy(), yy.numpy()\n", + "\n", + " c = ax.pcolor(xxn, yyn, acq.reshape(n, n), cmap=\"Blues\")\n", + " fig.colorbar(c)\n", + " ax.set_title(f\"Acquisition function - s: {fidelity}\")\n", + "\n", + " ax.plot(*history[[\"x1\", \"x2\"]][history[\"feasible\"]].to_numpy().T, \".C1\")\n", + " ax.plot(*history[[\"x1\", \"x2\"]][~history[\"feasible\"]].to_numpy().T, \".C2\")\n", + "\n", + " ax.plot(*history[[\"x1\", \"x2\"]].to_numpy()[-1].T, \"+\")\n", + "\n", + "\n", + "candidate = pd.DataFrame(X.generator.generate(1), index=[0])\n", + "print(candidate[[\"x1\", \"x2\"]].to_numpy())\n", + "ax.plot(*candidate[[\"x1\", \"x2\"]].to_numpy()[0], \"o\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "start_time": "2023-09-20T14:37:17.294215100Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:58:40.149385Z", + "iopub.status.busy": "2024-09-13T15:58:40.149271Z", + "iopub.status.idle": "2024-09-13T15:58:40.154183Z", + "shell.execute_reply": "2024-09-13T15:58:40.153956Z" + } + }, + "outputs": [], + "source": [ + "# examine lengthscale of the first objective\n", + "list(model.models[0].named_parameters())" + ] + } + ], + "metadata": { + "interpreter": { + "hash": "72034539424920dfb606fe3b820b3f27dca0cbf1c69938110810ec4641e275b1" + }, + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/scipy/latin_hypercube.ipynb b/docs/examples/scipy/latin_hypercube.ipynb new file mode 100644 index 0000000..684161e --- /dev/null +++ b/docs/examples/scipy/latin_hypercube.ipynb @@ -0,0 +1,191 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Latin Hypercube Generator Example\n", + "This notebook demonstrates basic use of the latin hypercube generator. This generator is a wrapper for the scipy latin hypercube method and allows users to efficiently sample functions (eg for surrogate models). Because the distribution of points depends on the number of sample requested, internally the xopt routine stores a batch of samples. The batch size is specified as an argument to the object's constructor. All other parameters to the scipy function are broken out this way and for a detailed explanation of what they do, the scipy documentation should be consulted." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:59:48.342031Z", + "iopub.status.busy": "2024-09-13T15:59:48.341760Z", + "iopub.status.idle": "2024-09-13T15:59:49.822807Z", + "shell.execute_reply": "2024-09-13T15:59:49.822468Z" + } + }, + "outputs": [], + "source": [ + "from copy import deepcopy\n", + "from xopt import Xopt, Evaluator\n", + "from xopt.generators.scipy.latin_hypercube import LatinHypercubeGenerator\n", + "from xopt.resources.test_functions.tnk import evaluate_TNK, tnk_vocs\n", + "import matplotlib.pyplot as plt\n", + "import numpy as np" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:59:49.824577Z", + "iopub.status.busy": "2024-09-13T15:59:49.824438Z", + "iopub.status.idle": "2024-09-13T15:59:49.831947Z", + "shell.execute_reply": "2024-09-13T15:59:49.831721Z" + } + }, + "outputs": [], + "source": [ + "# Create the test problem\n", + "vocs = deepcopy(tnk_vocs)\n", + "vocs.objectives = {}\n", + "vocs.observables = [\"y1\"]\n", + "evaluator = Evaluator(function=evaluate_TNK)\n", + "\n", + "# Create the generator and xopt object. Note: the samples are generated in\n", + "# batches and the batch size determines the arrangement of points to cover\n", + "# the bounded region of the variables.\n", + "generator = LatinHypercubeGenerator(vocs=vocs, batch_size=1024)\n", + "X = Xopt(generator=generator, evaluator=evaluator, vocs=vocs)\n", + "X" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:59:49.853822Z", + "iopub.status.busy": "2024-09-13T15:59:49.853693Z", + "iopub.status.idle": "2024-09-13T15:59:52.771762Z", + "shell.execute_reply": "2024-09-13T15:59:52.771514Z" + } + }, + "outputs": [], + "source": [ + "# Sample the function a number of times using latin hypercube points\n", + "for _ in range(1024):\n", + " X.step()\n", + "X.data.head()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:59:52.773315Z", + "iopub.status.busy": "2024-09-13T15:59:52.773198Z", + "iopub.status.idle": "2024-09-13T15:59:52.954069Z", + "shell.execute_reply": "2024-09-13T15:59:52.953771Z" + } + }, + "outputs": [], + "source": [ + "# Plot the data\n", + "plt.scatter(X.data[\"x1\"], X.data[\"x2\"], c=X.data[\"y1\"])\n", + "plt.xlabel(\"x1\")\n", + "plt.ylabel(\"x2\")\n", + "plt.colorbar(label=\"y1\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Distribution of Latin Hypercube points\n", + "Points in latin hypercube sampling are arranged in a grid such that none occupy the same row or column. That is, in chess it is similar to having n rooks on the board which cannot take each other. We can demonstrate this in the sampler by turning off the \"scramble\" feature (turned on by default)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:59:52.956942Z", + "iopub.status.busy": "2024-09-13T15:59:52.956849Z", + "iopub.status.idle": "2024-09-13T15:59:53.101131Z", + "shell.execute_reply": "2024-09-13T15:59:53.100871Z" + } + }, + "outputs": [], + "source": [ + "n = 16\n", + "generator = LatinHypercubeGenerator(vocs=vocs, batch_size=n, scramble=False, seed=0)\n", + "X = Xopt(generator=generator, evaluator=evaluator, vocs=vocs)\n", + "for _ in range(n):\n", + " X.step()\n", + "\n", + "plt.scatter(X.data[\"x1\"], X.data[\"x2\"], c=X.data[\"y1\"])\n", + "plt.xlabel(\"x1\")\n", + "plt.ylabel(\"x2\")\n", + "plt.colorbar(label=\"y1\")\n", + "\n", + "plt.hlines(np.linspace(0, 3.1416, n + 1), 0, 3.1416, color=\"k\")\n", + "plt.vlines(np.linspace(0, 3.1416, n + 1), 0, 3.1416, color=\"k\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The scramble feature will randomize the location of the points within each square while still maintaining the latin hypercube style cells." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:59:53.102570Z", + "iopub.status.busy": "2024-09-13T15:59:53.102481Z", + "iopub.status.idle": "2024-09-13T15:59:53.242827Z", + "shell.execute_reply": "2024-09-13T15:59:53.242558Z" + } + }, + "outputs": [], + "source": [ + "n = 16\n", + "generator = LatinHypercubeGenerator(vocs=vocs, batch_size=n, scramble=True, seed=0)\n", + "X = Xopt(generator=generator, evaluator=evaluator, vocs=vocs)\n", + "for _ in range(n):\n", + " X.step()\n", + "\n", + "plt.scatter(X.data[\"x1\"], X.data[\"x2\"], c=X.data[\"y1\"])\n", + "plt.xlabel(\"x1\")\n", + "plt.ylabel(\"x2\")\n", + "plt.colorbar(label=\"y1\")\n", + "\n", + "plt.hlines(np.linspace(0, 3.1416, n + 1), 0, 3.1416, color=\"k\")\n", + "plt.vlines(np.linspace(0, 3.1416, n + 1), 0, 3.1416, color=\"k\")" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/sequential/extremum_seeking.ipynb b/docs/examples/sequential/extremum_seeking.ipynb new file mode 100644 index 0000000..d541de3 --- /dev/null +++ b/docs/examples/sequential/extremum_seeking.ipynb @@ -0,0 +1,952 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "6f4b8676-940b-4a69-b495-df62bbc6e2fa", + "metadata": {}, + "source": [ + "## Extremum Seeking Optimization\n", + "\n", + "In this example we demonstrate extremum seeking optimization. The optimum of the test evaluate function would drift around a center point and we would be trying to follow the trend by applying extremum seeking technique." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "78534aeb-5ab2-4a3c-964c-4e080c7e953f", + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T20:53:47.373776100Z", + "start_time": "2023-09-06T20:53:44.301943600Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:34.524501Z", + "iopub.status.busy": "2024-09-13T15:59:34.524221Z", + "iopub.status.idle": "2024-09-13T15:59:35.714970Z", + "shell.execute_reply": "2024-09-13T15:59:35.714690Z" + } + }, + "outputs": [], + "source": [ + "import numpy as np\n", + "from xopt.generators.sequential.extremumseeking import ExtremumSeekingGenerator\n", + "from xopt.vocs import VOCS\n", + "from xopt.evaluator import Evaluator\n", + "from xopt import Xopt\n", + "from tqdm.auto import tqdm\n", + "import os\n", + "\n", + "import pandas as pd\n", + "\n", + "import matplotlib.pyplot as plt\n", + "\n", + "import warnings\n", + "\n", + "warnings.filterwarnings(\"ignore\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "7fb27b941602401d91542211134fc71a", + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T20:53:44.299944200Z", + "start_time": "2023-09-06T20:53:44.286945900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:35.716692Z", + "iopub.status.busy": "2024-09-13T15:59:35.716547Z", + "iopub.status.idle": "2024-09-13T15:59:35.718401Z", + "shell.execute_reply": "2024-09-13T15:59:35.718133Z" + } + }, + "outputs": [], + "source": [ + "# set values if testing\n", + "SMOKE_TEST = os.environ.get(\"SMOKE_TEST\")\n", + "NUM_STEPS = 10 if SMOKE_TEST else 1000" + ] + }, + { + "cell_type": "markdown", + "id": "fe8297c8-90e2-4e40-ab0b-63a9fe655aed", + "metadata": {}, + "source": [ + "### Extremum seeking test problem\n", + "\n", + "This test problem is a 10-D quadratic function, with its optimum drifting around the initial position. We also add some noise to make the problem more realistic." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "35171e8a-ea8f-4cbb-b1a0-d01213e0bbcc", + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T20:53:47.397804100Z", + "start_time": "2023-09-06T20:53:47.376774600Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:35.719793Z", + "iopub.status.busy": "2024-09-13T15:59:35.719685Z", + "iopub.status.idle": "2024-09-13T15:59:35.722556Z", + "shell.execute_reply": "2024-09-13T15:59:35.722342Z" + } + }, + "outputs": [], + "source": [ + "np.random.seed(42) # set deterministic run\n", + "\n", + "nES = 10\n", + "\n", + "# This global dict is used as a counter to emulate drifting\n", + "states = {\"count\": 0}\n", + "\n", + "# This is the unknown optimal point\n", + "p_opt = 1.5 * (2 * np.random.rand(nES) - 1)\n", + "\n", + "# Various frequencies for unknown points\n", + "w_opt = 0.25 + 2 * np.random.rand(nES)\n", + "\n", + "\n", + "def f_ES_minimize(input_dict):\n", + " p = []\n", + " for i in range(10):\n", + " p.append(input_dict[f\"p{i}\"])\n", + " p = np.array(p)\n", + "\n", + " # Vary the optimal point with time\n", + " p_opt_i = np.zeros(nES)\n", + " i = states[\"count\"]\n", + "\n", + " outcome_dict = {}\n", + " for n in np.arange(nES):\n", + " p_opt_i[n] = p_opt[n] * (1 + np.sin(2 * np.pi * w_opt[n] * i / 2000))\n", + " # This simple cost will be distance from the optimal point\n", + " f_val = np.sum((p - p_opt_i) ** 2) + 0.1 * np.random.randn()\n", + "\n", + " states[\"count\"] += 1\n", + " outcome_dict = {\"f\": f_val, \"p_opt\": pd.Series(p_opt_i)}\n", + "\n", + " return outcome_dict" + ] + }, + { + "cell_type": "markdown", + "id": "9638b784-fa2f-4a94-900c-c66c8b0ea58b", + "metadata": {}, + "source": [ + "### Run ES on the test problem (YAML method)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "8fac03d4-64f7-4773-973c-850b977a888e", + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T20:53:47.422816800Z", + "start_time": "2023-09-06T20:53:47.393777300Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:35.724072Z", + "iopub.status.busy": "2024-09-13T15:59:35.723965Z", + "iopub.status.idle": "2024-09-13T15:59:35.732244Z", + "shell.execute_reply": "2024-09-13T15:59:35.732011Z" + } + }, + "outputs": [], + "source": [ + "YAML = \"\"\"\n", + "max_evaluations: 5000\n", + "generator:\n", + " name: extremum_seeking\n", + " k: 2.0\n", + " oscillation_size: 0.1\n", + " decay_rate: 1.0\n", + "evaluator:\n", + " function: __main__.f_ES_minimize\n", + "vocs:\n", + " variables:\n", + " p0: [-2, 2]\n", + " p1: [-2, 2]\n", + " p2: [-2, 2]\n", + " p3: [-2, 2]\n", + " p4: [-2, 2]\n", + " p5: [-2, 2]\n", + " p6: [-2, 2]\n", + " p7: [-2, 2]\n", + " p8: [-2, 2]\n", + " p9: [-2, 2]\n", + " objectives:\n", + " f: MINIMIZE\n", + "\"\"\"\n", + "\n", + "X = Xopt.from_yaml(YAML)\n", + "X.max_evaluations = NUM_STEPS\n", + "\n", + "X" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "e16ab267-8b5e-4616-b552-2b0410c5b75f", + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T20:53:47.477800200Z", + "start_time": "2023-09-06T20:53:47.425774500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:35.733578Z", + "iopub.status.busy": "2024-09-13T15:59:35.733491Z", + "iopub.status.idle": "2024-09-13T15:59:35.739902Z", + "shell.execute_reply": "2024-09-13T15:59:35.739607Z" + }, + "tags": [] + }, + "outputs": [], + "source": [ + "# Reset global counter to guarantee deterministic optimization\n", + "states[\"count\"] = 0\n", + "\n", + "X.random_evaluate(1)\n", + "X.step()" + ] + }, + { + "cell_type": "markdown", + "id": "54acb14d-2b25-4f2e-a3e9-fecb61af552f", + "metadata": {}, + "source": [ + "Now you can go directly to the [Visualization](#Visualization) section and check out the results." + ] + }, + { + "cell_type": "markdown", + "id": "4d688915-bdca-4d0f-baaa-5c50cfd80d79", + "metadata": {}, + "source": [ + "### Run ES on the test problem (API method)" + ] + }, + { + "cell_type": "markdown", + "id": "8f0a6f75-7f92-47ee-828d-ad7435932cf2", + "metadata": {}, + "source": [ + "#### VOCS\n", + "\n", + "We'll set the bounds for all the variables pi to [-2, 2]." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "bd028b25-f395-43ed-8473-2dc950ff72c3", + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T20:53:47.484799800Z", + "start_time": "2023-09-06T20:53:47.451773900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:35.741812Z", + "iopub.status.busy": "2024-09-13T15:59:35.741688Z", + "iopub.status.idle": "2024-09-13T15:59:35.743467Z", + "shell.execute_reply": "2024-09-13T15:59:35.743235Z" + } + }, + "outputs": [], + "source": [ + "variables = {}\n", + "for i in range(nES):\n", + " variables[f\"p{i}\"] = [-2, 2]\n", + "\n", + "vocs = VOCS(\n", + " variables=variables,\n", + " objectives={\"f\": \"MINIMIZE\"},\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "0af5b8c7-4b3a-4a62-b92b-539899d11109", + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T20:53:47.484799800Z", + "start_time": "2023-09-06T20:53:47.477800200Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:35.744764Z", + "iopub.status.busy": "2024-09-13T15:59:35.744679Z", + "iopub.status.idle": "2024-09-13T15:59:35.746792Z", + "shell.execute_reply": "2024-09-13T15:59:35.746571Z" + } + }, + "outputs": [], + "source": [ + "vocs" + ] + }, + { + "cell_type": "markdown", + "id": "5354659c-cc30-4d70-8659-0fefd43ef0f0", + "metadata": {}, + "source": [ + "#### Evaluator" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "efafda0b-7282-4027-a1f3-f96454c114bd", + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T20:53:47.495775300Z", + "start_time": "2023-09-06T20:53:47.482775600Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:35.748148Z", + "iopub.status.busy": "2024-09-13T15:59:35.748053Z", + "iopub.status.idle": "2024-09-13T15:59:35.750066Z", + "shell.execute_reply": "2024-09-13T15:59:35.749852Z" + } + }, + "outputs": [], + "source": [ + "evaluator = Evaluator(function=f_ES_minimize)" + ] + }, + { + "cell_type": "markdown", + "id": "d6c58dcc-0b45-4408-a428-1681098a6a4a", + "metadata": {}, + "source": [ + "#### Generator" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "445daa23-5f97-4a82-bd59-57d9cbae6ac1", + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T20:53:47.537805600Z", + "start_time": "2023-09-06T20:53:47.496774Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:35.751404Z", + "iopub.status.busy": "2024-09-13T15:59:35.751303Z", + "iopub.status.idle": "2024-09-13T15:59:35.753159Z", + "shell.execute_reply": "2024-09-13T15:59:35.752943Z" + } + }, + "outputs": [], + "source": [ + "generator = ExtremumSeekingGenerator(vocs=vocs)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2e679d3f", + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T20:53:47.546774400Z", + "start_time": "2023-09-06T20:53:47.511775100Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:35.754526Z", + "iopub.status.busy": "2024-09-13T15:59:35.754424Z", + "iopub.status.idle": "2024-09-13T15:59:35.756451Z", + "shell.execute_reply": "2024-09-13T15:59:35.756213Z" + } + }, + "outputs": [], + "source": [ + "generator.dict()" + ] + }, + { + "cell_type": "markdown", + "id": "f5d375ac-a629-4d5e-8af9-becd47475bda", + "metadata": {}, + "source": [ + "Note that ES has 3 hyper-parameters: `k`, `oscillation_size`, and `decay_rate`.\n", + "\n", + "- `k`: ES feedback gain (set `k < 0` for maximization instead of minimization)\n", + "- `oscillation_size`: ES dithering size\n", + "- `decay_rate`: This value is optional, it causes the oscillation sizes to naturally decay. If you want the parameters to persistently oscillate without decay, set `decay_rate = 1.0`" + ] + }, + { + "cell_type": "markdown", + "id": "f4981983-1e64-43a1-ac90-f88546f9650a", + "metadata": {}, + "source": [ + "#### Run the optimization" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "10c77281-f49c-4cf7-bb2d-8a278cf00e23", + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T20:53:47.546774400Z", + "start_time": "2023-09-06T20:53:47.526775900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:35.757866Z", + "iopub.status.busy": "2024-09-13T15:59:35.757761Z", + "iopub.status.idle": "2024-09-13T15:59:35.759395Z", + "shell.execute_reply": "2024-09-13T15:59:35.759184Z" + } + }, + "outputs": [], + "source": [ + "X = Xopt(vocs=vocs, evaluator=evaluator, generator=generator)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "4f6ff00b-9abe-4bd1-9dac-7f5cb9293d0f", + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T20:53:47.560774400Z", + "start_time": "2023-09-06T20:53:47.541776400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:35.760702Z", + "iopub.status.busy": "2024-09-13T15:59:35.760605Z", + "iopub.status.idle": "2024-09-13T15:59:35.762182Z", + "shell.execute_reply": "2024-09-13T15:59:35.761972Z" + } + }, + "outputs": [], + "source": [ + "X.max_evaluations = NUM_STEPS" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d34576f0-8ce4-49a6-b360-a9155d777ae7", + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T20:54:42.396162600Z", + "start_time": "2023-09-06T20:53:47.558774900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:35.763499Z", + "iopub.status.busy": "2024-09-13T15:59:35.763418Z", + "iopub.status.idle": "2024-09-13T15:59:37.381345Z", + "shell.execute_reply": "2024-09-13T15:59:37.381023Z" + }, + "tags": [] + }, + "outputs": [], + "source": [ + "# Reset global counter to guarantee deterministic optimization\n", + "states[\"count\"] = 0\n", + "\n", + "X.random_evaluate(1)\n", + "for i in tqdm(range(NUM_STEPS - 1)):\n", + " X.step()" + ] + }, + { + "cell_type": "markdown", + "id": "9808d9af-a815-4995-911a-43bd9eb105da", + "metadata": {}, + "source": [ + "### Visualization" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "56859433-7310-4c27-be46-ad8ccad2ece8", + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T20:54:43.238169800Z", + "start_time": "2023-09-06T20:54:42.760171100Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:37.391614Z", + "iopub.status.busy": "2024-09-13T15:59:37.391496Z", + "iopub.status.idle": "2024-09-13T15:59:37.639540Z", + "shell.execute_reply": "2024-09-13T15:59:37.639274Z" + } + }, + "outputs": [], + "source": [ + "# Plot all results\n", + "plt.figure(1, figsize=(8, 10))\n", + "\n", + "plt.subplot(2, 1, 1)\n", + "plt.plot(X.data[\"f\"])\n", + "plt.ylabel(\"ES cost\")\n", + "plt.xticks([])\n", + "\n", + "\n", + "plt.subplot(2, 1, 2)\n", + "plt.plot(X.data[[f\"p{i}\" for i in range(10)]], alpha=0.25)\n", + "_p_opt = np.vstack(X.data[\"p_opt\"].values).astype(\n", + " float\n", + ") # do not use p_opt as var name!\n", + "plt.plot(_p_opt, \"k--\")\n", + "plt.plot(2 + np.zeros(NUM_STEPS), \"r\")\n", + "plt.plot(-2 + np.zeros(NUM_STEPS), \"r\")\n", + "plt.legend(frameon=False)\n", + "plt.ylabel(\"ES parameter\")\n", + "plt.xlabel(\"ES step\")\n", + "\n", + "plt.tight_layout()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "5840b360-a66f-486e-9a4c-44307e67737b", + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T20:54:44.514233700Z", + "start_time": "2023-09-06T20:54:43.238169800Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:37.642318Z", + "iopub.status.busy": "2024-09-13T15:59:37.642208Z", + "iopub.status.idle": "2024-09-13T15:59:38.208674Z", + "shell.execute_reply": "2024-09-13T15:59:38.208399Z" + } + }, + "outputs": [], + "source": [ + "# Plot Individual Parameter Trajectories\n", + "plt.figure(2, figsize=(15, 8))\n", + "\n", + "for n in np.arange(nES):\n", + " plt.subplot(2, 5, n + 1)\n", + " plt.plot(X.data[f\"p{n}\"], label=f\"$p^{{ES}}_{n + 1}$\")\n", + " plt.plot(_p_opt[:, n], \"k--\", label=f\"$p^*_{n + 1}$\")\n", + " plt.plot(2 + np.zeros(NUM_STEPS), \"r--\")\n", + " plt.plot(-2 + np.zeros(NUM_STEPS), \"r--\")\n", + " plt.ylim([-3, 5])\n", + " plt.legend(frameon=False, loc=1)\n", + " if n == 0:\n", + " plt.ylabel(\"parameters\")\n", + " elif n == 5:\n", + " plt.ylabel(\"parameters\")\n", + " else:\n", + " plt.yticks([])\n", + " if n > 4:\n", + " plt.xlabel(\"ES step\")\n", + " else:\n", + " plt.xticks([])\n", + "\n", + "plt.tight_layout()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "a5472d46", + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "xopt-dev", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.11.0" + }, + "widgets": { + "application/vnd.jupyter.widget-state+json": { + "state": { + "07e1db66e84a4190a4d349ec736dac8c": { + "model_module": "@jupyter-widgets/base", + "model_module_version": "2.0.0", + "model_name": "LayoutModel", + "state": { + "_model_module": "@jupyter-widgets/base", + "_model_module_version": "2.0.0", + "_model_name": "LayoutModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/base", + "_view_module_version": "2.0.0", + "_view_name": "LayoutView", + "align_content": null, + "align_items": null, + "align_self": null, + "border_bottom": null, + "border_left": null, + "border_right": null, + "border_top": null, + "bottom": null, + "display": null, + "flex": null, + "flex_flow": null, + "grid_area": null, + "grid_auto_columns": null, + "grid_auto_flow": null, + "grid_auto_rows": null, + "grid_column": null, + "grid_gap": null, + "grid_row": null, + "grid_template_areas": null, + "grid_template_columns": null, + "grid_template_rows": null, + "height": null, + "justify_content": null, + "justify_items": null, + "left": null, + "margin": null, + "max_height": null, + "max_width": null, + "min_height": null, + "min_width": null, + "object_fit": null, + "object_position": null, + "order": null, + "overflow": null, + "padding": null, + "right": null, + "top": null, + "visibility": null, + "width": null + } + }, + "098870d535c146a586a2418e0ee1763c": { + "model_module": "@jupyter-widgets/controls", + "model_module_version": "2.0.0", + "model_name": "HTMLStyleModel", + "state": { + "_model_module": "@jupyter-widgets/controls", + "_model_module_version": "2.0.0", + "_model_name": "HTMLStyleModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/base", + "_view_module_version": "2.0.0", + "_view_name": "StyleView", + "background": null, + "description_width": "", + "font_size": null, + "text_color": null + } + }, + "2131e8f12c5d4d38bb8f529ff2215785": { + "model_module": "@jupyter-widgets/controls", + "model_module_version": "2.0.0", + "model_name": "FloatProgressModel", + "state": { + "_dom_classes": [], + "_model_module": "@jupyter-widgets/controls", + "_model_module_version": "2.0.0", + "_model_name": "FloatProgressModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/controls", + "_view_module_version": "2.0.0", + "_view_name": "ProgressView", + "bar_style": "success", + "description": "", + "description_allow_html": false, + "layout": "IPY_MODEL_8630e86c087d48bfbe30701d5c2182c1", + "max": 1000, + "min": 0, + "orientation": "horizontal", + "style": "IPY_MODEL_a58d17d6a87b4ed4bda196c34d38ea7d", + "tabbable": null, + "tooltip": null, + "value": 1000 + } + }, + "538dc218e581495c881c62505a556378": { + "model_module": "@jupyter-widgets/base", + "model_module_version": "2.0.0", + "model_name": "LayoutModel", + "state": { + "_model_module": "@jupyter-widgets/base", + "_model_module_version": "2.0.0", + "_model_name": "LayoutModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/base", + "_view_module_version": "2.0.0", + "_view_name": "LayoutView", + "align_content": null, + "align_items": null, + "align_self": null, + "border_bottom": null, + "border_left": null, + "border_right": null, + "border_top": null, + "bottom": null, + "display": null, + "flex": null, + "flex_flow": null, + "grid_area": null, + "grid_auto_columns": null, + "grid_auto_flow": null, + "grid_auto_rows": null, + "grid_column": null, + "grid_gap": null, + "grid_row": null, + "grid_template_areas": null, + "grid_template_columns": null, + "grid_template_rows": null, + "height": null, + "justify_content": null, + "justify_items": null, + "left": null, + "margin": null, + "max_height": null, + "max_width": null, + "min_height": null, + "min_width": null, + "object_fit": null, + "object_position": null, + "order": null, + "overflow": null, + "padding": null, + "right": null, + "top": null, + "visibility": null, + "width": null + } + }, + "5499f69bb496479a8d997e031a7b0bd2": { + "model_module": "@jupyter-widgets/controls", + "model_module_version": "2.0.0", + "model_name": "HBoxModel", + "state": { + "_dom_classes": [], + "_model_module": "@jupyter-widgets/controls", + "_model_module_version": "2.0.0", + "_model_name": "HBoxModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/controls", + "_view_module_version": "2.0.0", + "_view_name": "HBoxView", + "box_style": "", + "children": [ + "IPY_MODEL_e1fdb3bb19ba4c20a832bc4001793a7e", + "IPY_MODEL_2131e8f12c5d4d38bb8f529ff2215785", + "IPY_MODEL_7bff28483fb34267894b86e720997886" + ], + "layout": "IPY_MODEL_7aaeb02e4bba482191c038e0409eddf9", + "tabbable": null, + "tooltip": null + } + }, + "7aaeb02e4bba482191c038e0409eddf9": { + "model_module": "@jupyter-widgets/base", + "model_module_version": "2.0.0", + "model_name": "LayoutModel", + "state": { + "_model_module": "@jupyter-widgets/base", + "_model_module_version": "2.0.0", + "_model_name": "LayoutModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/base", + "_view_module_version": "2.0.0", + "_view_name": "LayoutView", + "align_content": null, + "align_items": null, + "align_self": null, + "border_bottom": null, + "border_left": null, + "border_right": null, + "border_top": null, + "bottom": null, + "display": null, + "flex": null, + "flex_flow": null, + "grid_area": null, + "grid_auto_columns": null, + "grid_auto_flow": null, + "grid_auto_rows": null, + "grid_column": null, + "grid_gap": null, + "grid_row": null, + "grid_template_areas": null, + "grid_template_columns": null, + "grid_template_rows": null, + "height": null, + "justify_content": null, + "justify_items": null, + "left": null, + "margin": null, + "max_height": null, + "max_width": null, + "min_height": null, + "min_width": null, + "object_fit": null, + "object_position": null, + "order": null, + "overflow": null, + "padding": null, + "right": null, + "top": null, + "visibility": null, + "width": null + } + }, + "7bff28483fb34267894b86e720997886": { + "model_module": "@jupyter-widgets/controls", + "model_module_version": "2.0.0", + "model_name": "HTMLModel", + "state": { + "_dom_classes": [], + "_model_module": "@jupyter-widgets/controls", + "_model_module_version": "2.0.0", + "_model_name": "HTMLModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/controls", + "_view_module_version": "2.0.0", + "_view_name": "HTMLView", + "description": "", + "description_allow_html": false, + "layout": "IPY_MODEL_07e1db66e84a4190a4d349ec736dac8c", + "placeholder": "​", + "style": "IPY_MODEL_e586742ec9ea4692b88b5af78219a35c", + "tabbable": null, + "tooltip": null, + "value": " 1000/1000 [00:01<00:00, 626.38it/s]" + } + }, + "8630e86c087d48bfbe30701d5c2182c1": { + "model_module": "@jupyter-widgets/base", + "model_module_version": "2.0.0", + "model_name": "LayoutModel", + "state": { + "_model_module": "@jupyter-widgets/base", + "_model_module_version": "2.0.0", + "_model_name": "LayoutModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/base", + "_view_module_version": "2.0.0", + "_view_name": "LayoutView", + "align_content": null, + "align_items": null, + "align_self": null, + "border_bottom": null, + "border_left": null, + "border_right": null, + "border_top": null, + "bottom": null, + "display": null, + "flex": null, + "flex_flow": null, + "grid_area": null, + "grid_auto_columns": null, + "grid_auto_flow": null, + "grid_auto_rows": null, + "grid_column": null, + "grid_gap": null, + "grid_row": null, + "grid_template_areas": null, + "grid_template_columns": null, + "grid_template_rows": null, + "height": null, + "justify_content": null, + "justify_items": null, + "left": null, + "margin": null, + "max_height": null, + "max_width": null, + "min_height": null, + "min_width": null, + "object_fit": null, + "object_position": null, + "order": null, + "overflow": null, + "padding": null, + "right": null, + "top": null, + "visibility": null, + "width": null + } + }, + "a58d17d6a87b4ed4bda196c34d38ea7d": { + "model_module": "@jupyter-widgets/controls", + "model_module_version": "2.0.0", + "model_name": "ProgressStyleModel", + "state": { + "_model_module": "@jupyter-widgets/controls", + "_model_module_version": "2.0.0", + "_model_name": "ProgressStyleModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/base", + "_view_module_version": "2.0.0", + "_view_name": "StyleView", + "bar_color": null, + "description_width": "" + } + }, + "e1fdb3bb19ba4c20a832bc4001793a7e": { + "model_module": "@jupyter-widgets/controls", + "model_module_version": "2.0.0", + "model_name": "HTMLModel", + "state": { + "_dom_classes": [], + "_model_module": "@jupyter-widgets/controls", + "_model_module_version": "2.0.0", + "_model_name": "HTMLModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/controls", + "_view_module_version": "2.0.0", + "_view_name": "HTMLView", + "description": "", + "description_allow_html": false, + "layout": "IPY_MODEL_538dc218e581495c881c62505a556378", + "placeholder": "​", + "style": "IPY_MODEL_098870d535c146a586a2418e0ee1763c", + "tabbable": null, + "tooltip": null, + "value": "100%" + } + }, + "e586742ec9ea4692b88b5af78219a35c": { + "model_module": "@jupyter-widgets/controls", + "model_module_version": "2.0.0", + "model_name": "HTMLStyleModel", + "state": { + "_model_module": "@jupyter-widgets/controls", + "_model_module_version": "2.0.0", + "_model_name": "HTMLStyleModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/base", + "_view_module_version": "2.0.0", + "_view_name": "StyleView", + "background": null, + "description_width": "", + "font_size": null, + "text_color": null + } + } + }, + "version_major": 2, + "version_minor": 0 + } + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/examples/sequential/neldermead.ipynb b/docs/examples/sequential/neldermead.ipynb new file mode 100644 index 0000000..6b899f6 --- /dev/null +++ b/docs/examples/sequential/neldermead.ipynb @@ -0,0 +1,827 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Nelder-Mead Generator adapted from SciPy\n", + "\n", + "Most of the algorithms in scipy.optimize are self-contained functions that operate on the user-provided `func`. Xopt has adapted the Nelder-Mead directly from scipy.optimize to be in a generator form. This allows for the manual stepping through the algorithm.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:44:49.812021200Z", + "start_time": "2023-10-30T17:44:49.674945300Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:55.290406Z", + "iopub.status.busy": "2024-09-13T15:59:55.290130Z", + "iopub.status.idle": "2024-09-13T15:59:56.629085Z", + "shell.execute_reply": "2024-09-13T15:59:56.628652Z" + } + }, + "outputs": [], + "source": [ + "from xopt.generators.sequential.neldermead import NelderMeadGenerator\n", + "from xopt import Evaluator, VOCS\n", + "from xopt.resources.test_functions.rosenbrock import rosenbrock\n", + "\n", + "import pandas as pd\n", + "\n", + "from xopt import Xopt\n", + "import numpy as np\n", + "\n", + "from scipy.optimize import fmin\n", + "\n", + "# from xopt import output_notebook\n", + "# output_notebook()\n", + "\n", + "import matplotlib.pyplot as plt" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Nelder-Mead optimization of the Rosenbrock function with Xopt" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:44:49.892121Z", + "start_time": "2023-10-30T17:44:49.680946600Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:56.630921Z", + "iopub.status.busy": "2024-09-13T15:59:56.630754Z", + "iopub.status.idle": "2024-09-13T15:59:56.770318Z", + "shell.execute_reply": "2024-09-13T15:59:56.769954Z" + } + }, + "outputs": [], + "source": [ + "YAML = \"\"\"\n", + "max_evaluations: 500\n", + "generator:\n", + " name: neldermead\n", + " adaptive: true\n", + "evaluator:\n", + " function: xopt.resources.test_functions.rosenbrock.evaluate_rosenbrock\n", + "vocs:\n", + " variables:\n", + " x0: [-5, 5]\n", + " x1: [-5, 5]\n", + " objectives: {y: MINIMIZE}\n", + "\"\"\"\n", + "X = Xopt.from_yaml(YAML)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:44:49.974002700Z", + "start_time": "2023-10-30T17:44:49.689493800Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:56.772033Z", + "iopub.status.busy": "2024-09-13T15:59:56.771899Z", + "iopub.status.idle": "2024-09-13T15:59:56.773651Z", + "shell.execute_reply": "2024-09-13T15:59:56.773421Z" + } + }, + "outputs": [], + "source": [ + "XMIN = [1, 1] # True minimum" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:44:50.195902300Z", + "start_time": "2023-10-30T17:44:49.692491400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:56.774890Z", + "iopub.status.busy": "2024-09-13T15:59:56.774814Z", + "iopub.status.idle": "2024-09-13T15:59:56.900724Z", + "shell.execute_reply": "2024-09-13T15:59:56.900477Z" + } + }, + "outputs": [], + "source": [ + "X.random_evaluate(2)\n", + "X.run()\n", + "X.data" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:44:50.365947900Z", + "start_time": "2023-10-30T17:44:50.143890300Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:56.921439Z", + "iopub.status.busy": "2024-09-13T15:59:56.921315Z", + "iopub.status.idle": "2024-09-13T15:59:57.126519Z", + "shell.execute_reply": "2024-09-13T15:59:57.126249Z" + } + }, + "outputs": [], + "source": [ + "# Evaluation progression\n", + "X.data[\"y\"].plot()\n", + "plt.yscale(\"log\")\n", + "plt.xlabel(\"iteration\")\n", + "plt.ylabel(\"Rosenbrock value\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:44:50.365947900Z", + "start_time": "2023-10-30T17:44:50.334810200Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:57.128025Z", + "iopub.status.busy": "2024-09-13T15:59:57.127898Z", + "iopub.status.idle": "2024-09-13T15:59:57.130442Z", + "shell.execute_reply": "2024-09-13T15:59:57.130194Z" + } + }, + "outputs": [], + "source": [ + "# Minimum\n", + "dict(X.data.iloc[X.data[\"y\"].argmin()])" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Visualize" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:44:50.678806600Z", + "start_time": "2023-10-30T17:44:50.342942900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:57.131800Z", + "iopub.status.busy": "2024-09-13T15:59:57.131700Z", + "iopub.status.idle": "2024-09-13T15:59:57.350241Z", + "shell.execute_reply": "2024-09-13T15:59:57.349942Z" + } + }, + "outputs": [], + "source": [ + "fig, ax = plt.subplots(figsize=(8, 8))\n", + "\n", + "Xgrid, Ygrid = np.meshgrid(np.linspace(-2, 2, 201), np.linspace(-2, 2, 201))\n", + "\n", + "Zgrid = np.vectorize(lambda x, y: rosenbrock([x, y]))(Xgrid, Ygrid)\n", + "Zgrid = np.log(Zgrid + 1)\n", + "\n", + "ax.pcolormesh(Xgrid, Ygrid, Zgrid)\n", + "ax.contour(Xgrid, Ygrid, Zgrid, levels=10, colors=\"black\")\n", + "ax.set_xlabel(\"x0\")\n", + "ax.set_ylabel(\"x1\")\n", + "\n", + "\n", + "# Add all evaluations\n", + "ax.plot(X.data[\"x0\"], X.data[\"x1\"], color=\"red\", alpha=0.5, marker=\".\")\n", + "ax.scatter(XMIN[0], XMIN[1], 50, marker=\"o\", color=\"orange\", label=\"True minimum\")\n", + "ax.set_xlim(-2, 2)\n", + "ax.set_ylim(-2, 2)\n", + "# plt.legend()\n", + "ax.set_title(\"Xopt's Nelder-Mead progression\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:44:51.150914300Z", + "start_time": "2023-10-30T17:44:50.678806600Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:57.353700Z", + "iopub.status.busy": "2024-09-13T15:59:57.353586Z", + "iopub.status.idle": "2024-09-13T15:59:57.475442Z", + "shell.execute_reply": "2024-09-13T15:59:57.475164Z" + } + }, + "outputs": [], + "source": [ + "# Manually step the algorithm and collect simplexes\n", + "X = Xopt.from_yaml(YAML)\n", + "X.random_evaluate(1)\n", + "simplexes = []\n", + "for i in range(500):\n", + " X.step()\n", + " simplexes.append(X.generator.simplex)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:44:51.435380800Z", + "start_time": "2023-10-30T17:44:51.141912400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:57.476926Z", + "iopub.status.busy": "2024-09-13T15:59:57.476833Z", + "iopub.status.idle": "2024-09-13T15:59:57.642323Z", + "shell.execute_reply": "2024-09-13T15:59:57.642032Z" + } + }, + "outputs": [], + "source": [ + "def plot_simplex(simplex, ax=None):\n", + " x0 = simplex[\"x0\"]\n", + " x1 = simplex[\"x1\"]\n", + " x0 = np.append(x0, x0[0])\n", + " x1 = np.append(x1, x1[0])\n", + " ax.plot(x0, x1)\n", + "\n", + "\n", + "fig, ax = plt.subplots(figsize=(8, 8))\n", + "ax.pcolormesh(Xgrid, Ygrid, Zgrid)\n", + "# ax.contour(Xgrid, Ygrid, Zgrid, levels=10, colors='black')\n", + "ax.set_xlim(-2, 2)\n", + "ax.set_ylim(-2, 2)\n", + "ax.set_xlabel(\"x0\")\n", + "ax.set_ylabel(\"x1\")\n", + "ax.set_title(\"Nelder-Mead simplex progression\")\n", + "\n", + "ax.scatter(XMIN[0], XMIN[1], 50, marker=\"o\", color=\"orange\", label=\"True minimum\")\n", + "\n", + "for simplex in simplexes:\n", + " plot_simplex(simplex, ax)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Compare with scipy.optimize.fmin Nelder-Mead\n", + "\n", + "Notice that fmin is much faster here. This is because the function runs very fast, so the internal Xopt bookkeeping overhead dominates.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:44:51.449604Z", + "start_time": "2023-10-30T17:44:51.439896600Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:57.644248Z", + "iopub.status.busy": "2024-09-13T15:59:57.644134Z", + "iopub.status.idle": "2024-09-13T15:59:57.647915Z", + "shell.execute_reply": "2024-09-13T15:59:57.647663Z" + } + }, + "outputs": [], + "source": [ + "result = fmin(rosenbrock, [-1, -1])\n", + "result" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:44:51.464852Z", + "start_time": "2023-10-30T17:44:51.449604Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:57.649286Z", + "iopub.status.busy": "2024-09-13T15:59:57.649209Z", + "iopub.status.idle": "2024-09-13T15:59:57.652369Z", + "shell.execute_reply": "2024-09-13T15:59:57.652131Z" + } + }, + "outputs": [], + "source": [ + "X = Xopt.from_yaml(YAML)\n", + "X.random_evaluate(1)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:44:51.953260600Z", + "start_time": "2023-10-30T17:44:51.458863500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:57.653687Z", + "iopub.status.busy": "2024-09-13T15:59:57.653609Z", + "iopub.status.idle": "2024-09-13T15:59:57.774912Z", + "shell.execute_reply": "2024-09-13T15:59:57.774652Z" + } + }, + "outputs": [], + "source": [ + "X.run()\n", + "# Almost exactly the same number evaluations.\n", + "len(X.data)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:44:51.953260600Z", + "start_time": "2023-10-30T17:44:51.947939500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:57.776356Z", + "iopub.status.busy": "2024-09-13T15:59:57.776254Z", + "iopub.status.idle": "2024-09-13T15:59:57.778516Z", + "shell.execute_reply": "2024-09-13T15:59:57.778285Z" + } + }, + "outputs": [], + "source": [ + "# results are the same\n", + "xbest = X.data.iloc[X.data[\"y\"].argmin()]\n", + "xbest[\"x0\"] == result[0], xbest[\"x1\"] == result[1]" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# NelderMeadGenerator object" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:44:51.961646200Z", + "start_time": "2023-10-30T17:44:51.956765600Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:57.779845Z", + "iopub.status.busy": "2024-09-13T15:59:57.779744Z", + "iopub.status.idle": "2024-09-13T15:59:57.781773Z", + "shell.execute_reply": "2024-09-13T15:59:57.781561Z" + } + }, + "outputs": [], + "source": [ + "NelderMeadGenerator.model_fields" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:44:51.983064100Z", + "start_time": "2023-10-30T17:44:51.963646900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:57.783087Z", + "iopub.status.busy": "2024-09-13T15:59:57.782990Z", + "iopub.status.idle": "2024-09-13T15:59:57.786326Z", + "shell.execute_reply": "2024-09-13T15:59:57.786079Z" + } + }, + "outputs": [], + "source": [ + "Xbest = [33, 44]\n", + "\n", + "\n", + "def f(inputs, verbose=False):\n", + " if verbose:\n", + " print(f\"evaluate f({inputs})\")\n", + " x0 = inputs[\"x0\"]\n", + " x1 = inputs[\"x1\"]\n", + "\n", + " # if x0 < 10:\n", + " # raise ValueError('test XXXX')\n", + "\n", + " y = (x0 - Xbest[0]) ** 2 + (x1 - Xbest[1]) ** 2\n", + "\n", + " return {\"y\": y}\n", + "\n", + "\n", + "ev = Evaluator(function=f)\n", + "vocs = VOCS(\n", + " variables={\"x0\": [-100, 100], \"x1\": [-100, 100]}, objectives={\"y\": \"MINIMIZE\"}\n", + ")\n", + "vocs.json()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:44:52.060007300Z", + "start_time": "2023-10-30T17:44:51.971425700Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:57.787580Z", + "iopub.status.busy": "2024-09-13T15:59:57.787501Z", + "iopub.status.idle": "2024-09-13T15:59:57.789464Z", + "shell.execute_reply": "2024-09-13T15:59:57.789240Z" + } + }, + "outputs": [], + "source": [ + "# check output\n", + "f(vocs.random_inputs()[0])" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:44:52.061007300Z", + "start_time": "2023-10-30T17:44:51.975482700Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:57.790962Z", + "iopub.status.busy": "2024-09-13T15:59:57.790884Z", + "iopub.status.idle": "2024-09-13T15:59:57.793148Z", + "shell.execute_reply": "2024-09-13T15:59:57.792936Z" + } + }, + "outputs": [], + "source": [ + "G = NelderMeadGenerator(vocs=vocs, initial_point={\"x0\": 0, \"x1\": 0})\n", + "inputs = G.generate(1)\n", + "inputs" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:44:52.063008Z", + "start_time": "2023-10-30T17:44:51.981063900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:57.794425Z", + "iopub.status.busy": "2024-09-13T15:59:57.794345Z", + "iopub.status.idle": "2024-09-13T15:59:57.796438Z", + "shell.execute_reply": "2024-09-13T15:59:57.796201Z" + } + }, + "outputs": [], + "source": [ + "# Further generate calls will continue to produce same point, as with BO\n", + "G.generate(1)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:44:52.064007900Z", + "start_time": "2023-10-30T17:44:51.987724400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:57.797783Z", + "iopub.status.busy": "2024-09-13T15:59:57.797707Z", + "iopub.status.idle": "2024-09-13T15:59:57.799517Z", + "shell.execute_reply": "2024-09-13T15:59:57.799279Z" + } + }, + "outputs": [], + "source": [ + "ev.evaluate(inputs[0])" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:44:52.065008300Z", + "start_time": "2023-10-30T17:44:51.991721600Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:57.800848Z", + "iopub.status.busy": "2024-09-13T15:59:57.800768Z", + "iopub.status.idle": "2024-09-13T15:59:57.803515Z", + "shell.execute_reply": "2024-09-13T15:59:57.803286Z" + } + }, + "outputs": [], + "source": [ + "# Adding new data will advance state to next step, and next generate() will yield new point\n", + "G.add_data(pd.DataFrame(inputs[0] | ev.evaluate(inputs[0]), index=[0]))\n", + "G.generate(1)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:44:52.065008300Z", + "start_time": "2023-10-30T17:44:52.000489700Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:57.804779Z", + "iopub.status.busy": "2024-09-13T15:59:57.804698Z", + "iopub.status.idle": "2024-09-13T15:59:57.806303Z", + "shell.execute_reply": "2024-09-13T15:59:57.806080Z" + } + }, + "outputs": [], + "source": [ + "# Create Xopt object\n", + "X = Xopt(\n", + " evaluator=ev,\n", + " vocs=vocs,\n", + " generator=NelderMeadGenerator(vocs=vocs),\n", + " max_evaluations=100,\n", + ")\n", + "\n", + "# Optional: give an initial pioint\n", + "X.generator.initial_point = {\"x0\": 0, \"x1\": 0}" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:44:52.813583500Z", + "start_time": "2023-10-30T17:44:52.002994200Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:57.807568Z", + "iopub.status.busy": "2024-09-13T15:59:57.807488Z", + "iopub.status.idle": "2024-09-13T15:59:57.973465Z", + "shell.execute_reply": "2024-09-13T15:59:57.973221Z" + } + }, + "outputs": [], + "source": [ + "X.run()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:44:52.832798100Z", + "start_time": "2023-10-30T17:44:52.825250500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:57.981477Z", + "iopub.status.busy": "2024-09-13T15:59:57.981399Z", + "iopub.status.idle": "2024-09-13T15:59:57.983453Z", + "shell.execute_reply": "2024-09-13T15:59:57.983225Z" + } + }, + "outputs": [], + "source": [ + "# This shows the latest simplex\n", + "X.generator.simplex" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:44:53.022138900Z", + "start_time": "2023-10-30T17:44:52.830797500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:57.984820Z", + "iopub.status.busy": "2024-09-13T15:59:57.984744Z", + "iopub.status.idle": "2024-09-13T15:59:58.084711Z", + "shell.execute_reply": "2024-09-13T15:59:58.084426Z" + } + }, + "outputs": [], + "source": [ + "X.data[\"y\"].plot()\n", + "plt.yscale(\"log\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:44:53.162747600Z", + "start_time": "2023-10-30T17:44:53.024139500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:58.086142Z", + "iopub.status.busy": "2024-09-13T15:59:58.086038Z", + "iopub.status.idle": "2024-09-13T15:59:58.156876Z", + "shell.execute_reply": "2024-09-13T15:59:58.156616Z" + } + }, + "outputs": [], + "source": [ + "fig, ax = plt.subplots()\n", + "X.data.plot(\"x0\", \"x1\", ax=ax, color=\"black\", alpha=0.5)\n", + "ax.scatter(Xbest[0], Xbest[1], marker=\"x\", color=\"red\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:44:53.162747600Z", + "start_time": "2023-10-30T17:44:53.152349900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:58.158257Z", + "iopub.status.busy": "2024-09-13T15:59:58.158172Z", + "iopub.status.idle": "2024-09-13T15:59:58.160476Z", + "shell.execute_reply": "2024-09-13T15:59:58.160263Z" + } + }, + "outputs": [], + "source": [ + "# This is the raw internal state of the generator\n", + "a = X.generator.current_state\n", + "a" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 5-dimensional Rosenbrock\n", + "\n", + "`evaluate_rosenbrock` works for arbitrary dimensions, so adding more variables to `vocs` transforms this problem." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:45:23.048760200Z", + "start_time": "2023-10-30T17:45:22.988273100Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:58.335288Z", + "iopub.status.busy": "2024-09-13T15:59:58.335179Z", + "iopub.status.idle": "2024-09-13T15:59:58.338386Z", + "shell.execute_reply": "2024-09-13T15:59:58.338158Z" + } + }, + "outputs": [], + "source": [ + "YAML = \"\"\"\n", + "max_evaluations: 500\n", + "generator:\n", + " name: neldermead\n", + "evaluator:\n", + " function: xopt.resources.test_functions.rosenbrock.evaluate_rosenbrock\n", + "vocs:\n", + " variables:\n", + " x1: [-5, 5]\n", + " x2: [-5, 5]\n", + " x3: [-5, 5]\n", + " x4: [-5, 5]\n", + " x5: [-5, 5]\n", + " objectives:\n", + " y: MINIMIZE\n", + "\"\"\"\n", + "X = Xopt.from_yaml(YAML)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:45:27.799562100Z", + "start_time": "2023-10-30T17:45:22.996241200Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:58.339678Z", + "iopub.status.busy": "2024-09-13T15:59:58.339596Z", + "iopub.status.idle": "2024-09-13T15:59:59.299922Z", + "shell.execute_reply": "2024-09-13T15:59:59.299618Z" + } + }, + "outputs": [], + "source": [ + "X.random_evaluate(1)\n", + "X.run()\n", + "X.data[\"y\"].plot()\n", + "plt.yscale(\"log\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-30T17:45:28.180395600Z", + "start_time": "2023-10-30T17:45:27.804562400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:59:59.301516Z", + "iopub.status.busy": "2024-09-13T15:59:59.301406Z", + "iopub.status.idle": "2024-09-13T15:59:59.512342Z", + "shell.execute_reply": "2024-09-13T15:59:59.512091Z" + } + }, + "outputs": [], + "source": [ + "fig, ax = plt.subplots(figsize=(8, 8))\n", + "\n", + "Xgrid, Ygrid = np.meshgrid(np.linspace(-2, 2, 201), np.linspace(-2, 2, 201))\n", + "\n", + "Zgrid = np.vectorize(lambda x, y: rosenbrock([x, y, 1, 1, 1]))(\n", + " Xgrid, Ygrid\n", + ") # The minimum is at 1,1,1,1,1\n", + "Zgrid = np.log(Zgrid + 1)\n", + "\n", + "ax.pcolormesh(Xgrid, Ygrid, Zgrid)\n", + "ax.contour(Xgrid, Ygrid, Zgrid, levels=10, colors=\"black\")\n", + "ax.set_xlabel(\"x0\")\n", + "ax.set_ylabel(\"x1\")\n", + "\n", + "\n", + "# Add all evaluations\n", + "ax.plot(X.data[\"x1\"], X.data[\"x2\"], color=\"red\", alpha=0.5, marker=\".\")\n", + "ax.scatter(XMIN[0], XMIN[1], 50, marker=\"o\", color=\"orange\", label=\"True minimum\")\n", + "ax.set_xlim(-2, 2)\n", + "ax.set_ylim(-2, 2)\n", + "# plt.legend()\n", + "ax.set_title(\"Xopt's Nelder-Mead progression\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "xopt-dev", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.11.0" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/sequential/rcds.ipynb b/docs/examples/sequential/rcds.ipynb new file mode 100644 index 0000000..7e5005b --- /dev/null +++ b/docs/examples/sequential/rcds.ipynb @@ -0,0 +1,835 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "6f4b8676-940b-4a69-b495-df62bbc6e2fa", + "metadata": {}, + "source": [ + "## RCDS Optimization\n", + "\n", + "In this example we demonstrate RCDS optimization." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d05700a3-6853-4dae-bc87-3f9f37dea446", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-26T22:16:31.208636600Z", + "start_time": "2023-10-26T22:16:31.201806800Z" + }, + "tags": [] + }, + "outputs": [], + "source": [ + "# If you encounter the \"Initializing libomp.dylib, but found libomp.dylib already initialized.\" error\n", + "# Please run this cell\n", + "import os" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "78534aeb-5ab2-4a3c-964c-4e080c7e953f", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-26T22:16:34.557495800Z", + "start_time": "2023-10-26T22:16:31.210637400Z" + }, + "tags": [] + }, + "outputs": [], + "source": [ + "import numpy as np\n", + "from xopt.generators.sequential import RCDSGenerator\n", + "from xopt.vocs import VOCS\n", + "from xopt.evaluator import Evaluator\n", + "from xopt import Xopt\n", + "from tqdm.auto import tqdm\n", + "import warnings\n", + "\n", + "\n", + "warnings.filterwarnings(\"ignore\")\n", + "\n", + "os.environ[\"KMP_DUPLICATE_LIB_OK\"] = \"True\"" + ] + }, + { + "cell_type": "markdown", + "id": "fe8297c8-90e2-4e40-ab0b-63a9fe655aed", + "metadata": {}, + "source": [ + "### RCDS test problem\n", + "\n", + "This test problem is a 2-D quadratic function." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "35171e8a-ea8f-4cbb-b1a0-d01213e0bbcc", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-26T22:16:34.571463700Z", + "start_time": "2023-10-26T22:16:34.559463800Z" + } + }, + "outputs": [], + "source": [ + "def f_test(input_dict):\n", + " p = []\n", + " for i in range(2):\n", + " p.append(input_dict[f\"p{i}\"])\n", + "\n", + " obj = np.linalg.norm(p)\n", + " outcome_dict = {\"f\": obj}\n", + "\n", + " return outcome_dict" + ] + }, + { + "cell_type": "markdown", + "id": "9638b784-fa2f-4a94-900c-c66c8b0ea58b", + "metadata": {}, + "source": [ + "### Run RCDS on the test problem (YAML method)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "8fac03d4-64f7-4773-973c-850b977a888e", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-26T22:16:34.602490200Z", + "start_time": "2023-10-26T22:16:34.576462200Z" + } + }, + "outputs": [], + "source": [ + "YAML = \"\"\"\n", + "max_evaluations: 100\n", + "generator:\n", + " name: rcds\n", + " x0: null\n", + " init_mat: null\n", + " noise: 0.00001\n", + " step: 0.01\n", + " tol: 0.00001\n", + "evaluator:\n", + " function: __main__.f_test\n", + "vocs:\n", + " variables:\n", + " p0: [0, 1]\n", + " p1: [0, 1]\n", + " objectives:\n", + " f: MINIMIZE\n", + "\"\"\"\n", + "\n", + "X = Xopt.from_yaml(YAML)\n", + "X" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "e16ab267-8b5e-4616-b552-2b0410c5b75f", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-26T22:16:35.201462800Z", + "start_time": "2023-10-26T22:16:34.607463300Z" + }, + "tags": [] + }, + "outputs": [], + "source": [ + "X.random_evaluate(1)\n", + "X.run()" + ] + }, + { + "cell_type": "markdown", + "id": "54acb14d-2b25-4f2e-a3e9-fecb61af552f", + "metadata": {}, + "source": [ + "Now you can go directly to the [Visualization](#Visualization) section and check out the results." + ] + }, + { + "cell_type": "markdown", + "id": "eadf6cd3-24af-4b8b-8df0-9d85d0b26757", + "metadata": {}, + "source": [ + "### Run RCDS on the maximization test problem (YAML method)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "3e6c673c-4518-4db2-82ba-1ea9b5a11d53", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-26T22:16:34.602490200Z", + "start_time": "2023-10-26T22:16:34.576462200Z" + } + }, + "outputs": [], + "source": [ + "YAML = \"\"\"\n", + "max_evaluations: 400\n", + "generator:\n", + " name: rcds\n", + " x0: null\n", + " init_mat: null\n", + " noise: 1e-8\n", + " step: 0.01\n", + " tol: 0.00001\n", + "evaluator:\n", + " function: __main__.f_test\n", + "vocs:\n", + " variables:\n", + " p0: [1, 3]\n", + " p1: [-4, 2]\n", + " objectives:\n", + " f: MAXIMIZE\n", + "\"\"\"\n", + "\n", + "X = Xopt.from_yaml(YAML)\n", + "X" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "1f738c00-4a57-41a4-a0a8-2abf2584667f", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-26T22:16:35.201462800Z", + "start_time": "2023-10-26T22:16:34.607463300Z" + }, + "tags": [] + }, + "outputs": [], + "source": [ + "X.random_evaluate(1)\n", + "X.run()" + ] + }, + { + "cell_type": "markdown", + "id": "09a02bed-32f5-4d2a-945d-2fdcc4756af3", + "metadata": {}, + "source": [ + "Now you can go directly to the [Visualization](#Visualization) section and check out the results." + ] + }, + { + "cell_type": "markdown", + "id": "4d688915-bdca-4d0f-baaa-5c50cfd80d79", + "metadata": {}, + "source": [ + "### Run RCDS on the test problem (API method)" + ] + }, + { + "cell_type": "markdown", + "id": "8f0a6f75-7f92-47ee-828d-ad7435932cf2", + "metadata": {}, + "source": [ + "#### VOCS\n", + "\n", + "We'll set the bounds for all the variables pi to [0, 1]." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "bd028b25-f395-43ed-8473-2dc950ff72c3", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-26T22:16:35.216462Z", + "start_time": "2023-10-26T22:16:35.204461300Z" + } + }, + "outputs": [], + "source": [ + "n_var = 2" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "c99026b0-f595-4247-9695-6d0b067ceeca", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-26T22:16:35.239487Z", + "start_time": "2023-10-26T22:16:35.218462900Z" + } + }, + "outputs": [], + "source": [ + "variables = {}\n", + "for i in range(n_var):\n", + " variables[f\"p{i}\"] = [0, 1]\n", + "\n", + "vocs = VOCS(\n", + " variables=variables,\n", + " objectives={\"f\": \"MINIMIZE\"},\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "0af5b8c7-4b3a-4a62-b92b-539899d11109", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-26T22:16:35.247462100Z", + "start_time": "2023-10-26T22:16:35.233463200Z" + } + }, + "outputs": [], + "source": [ + "vocs" + ] + }, + { + "cell_type": "markdown", + "id": "5354659c-cc30-4d70-8659-0fefd43ef0f0", + "metadata": {}, + "source": [ + "#### Evaluator" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "efafda0b-7282-4027-a1f3-f96454c114bd", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-26T22:16:35.290491Z", + "start_time": "2023-10-26T22:16:35.249462300Z" + } + }, + "outputs": [], + "source": [ + "evaluator = Evaluator(function=f_test)" + ] + }, + { + "cell_type": "markdown", + "id": "d6c58dcc-0b45-4408-a428-1681098a6a4a", + "metadata": {}, + "source": [ + "#### Generator" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "445daa23-5f97-4a82-bd59-57d9cbae6ac1", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-26T22:16:35.296460300Z", + "start_time": "2023-10-26T22:16:35.263463700Z" + } + }, + "outputs": [], + "source": [ + "generator = RCDSGenerator(vocs=vocs)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "346fad29", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-26T22:16:35.297491800Z", + "start_time": "2023-10-26T22:16:35.290491Z" + } + }, + "outputs": [], + "source": [ + "generator.model_dump()" + ] + }, + { + "cell_type": "markdown", + "id": "f4981983-1e64-43a1-ac90-f88546f9650a", + "metadata": {}, + "source": [ + "#### Run the optimization" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "10c77281-f49c-4cf7-bb2d-8a278cf00e23", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-26T22:16:35.307490500Z", + "start_time": "2023-10-26T22:16:35.296460300Z" + } + }, + "outputs": [], + "source": [ + "X = Xopt(vocs=vocs, evaluator=evaluator, generator=generator)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "1632b55e-1dd0-49b2-9444-cfe32e30977b", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-26T22:16:35.907460800Z", + "start_time": "2023-10-26T22:16:35.308463400Z" + }, + "tags": [] + }, + "outputs": [], + "source": [ + "X.evaluate_data({\"p0\": 0.5, \"p1\": 0.5})" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "9bb04077-1562-430d-a661-de8cb8836b7d", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-26T22:16:35.907460800Z", + "start_time": "2023-10-26T22:16:35.308463400Z" + }, + "tags": [] + }, + "outputs": [], + "source": [ + "for i in tqdm(range(400)):\n", + " X.step()" + ] + }, + { + "cell_type": "markdown", + "id": "9808d9af-a815-4995-911a-43bd9eb105da", + "metadata": {}, + "source": [ + "### Visualization" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "651d6821-8069-4efb-8bad-56a87f7240e8", + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-26T22:16:36.402079200Z", + "start_time": "2023-10-26T22:16:35.911052600Z" + } + }, + "outputs": [], + "source": [ + "X.data.plot(y=\"f\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "096fa078-9cf9-43a0-8366-2ccd2280bcc0", + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.9" + }, + "widgets": { + "application/vnd.jupyter.widget-state+json": { + "state": { + "0464f9bccf1248feb2ae2081538d7b1d": { + "model_module": "@jupyter-widgets/base", + "model_module_version": "2.0.0", + "model_name": "LayoutModel", + "state": { + "_model_module": "@jupyter-widgets/base", + "_model_module_version": "2.0.0", + "_model_name": "LayoutModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/base", + "_view_module_version": "2.0.0", + "_view_name": "LayoutView", + "align_content": null, + "align_items": null, + "align_self": null, + "border_bottom": null, + "border_left": null, + "border_right": null, + "border_top": null, + "bottom": null, + "display": null, + "flex": null, + "flex_flow": null, + "grid_area": null, + "grid_auto_columns": null, + "grid_auto_flow": null, + "grid_auto_rows": null, + "grid_column": null, + "grid_gap": null, + "grid_row": null, + "grid_template_areas": null, + "grid_template_columns": null, + "grid_template_rows": null, + "height": null, + "justify_content": null, + "justify_items": null, + "left": null, + "margin": null, + "max_height": null, + "max_width": null, + "min_height": null, + "min_width": null, + "object_fit": null, + "object_position": null, + "order": null, + "overflow": null, + "padding": null, + "right": null, + "top": null, + "visibility": null, + "width": null + } + }, + "3d977298874a42d1b7432d67c99d5395": { + "model_module": "@jupyter-widgets/base", + "model_module_version": "2.0.0", + "model_name": "LayoutModel", + "state": { + "_model_module": "@jupyter-widgets/base", + "_model_module_version": "2.0.0", + "_model_name": "LayoutModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/base", + "_view_module_version": "2.0.0", + "_view_name": "LayoutView", + "align_content": null, + "align_items": null, + "align_self": null, + "border_bottom": null, + "border_left": null, + "border_right": null, + "border_top": null, + "bottom": null, + "display": null, + "flex": null, + "flex_flow": null, + "grid_area": null, + "grid_auto_columns": null, + "grid_auto_flow": null, + "grid_auto_rows": null, + "grid_column": null, + "grid_gap": null, + "grid_row": null, + "grid_template_areas": null, + "grid_template_columns": null, + "grid_template_rows": null, + "height": null, + "justify_content": null, + "justify_items": null, + "left": null, + "margin": null, + "max_height": null, + "max_width": null, + "min_height": null, + "min_width": null, + "object_fit": null, + "object_position": null, + "order": null, + "overflow": null, + "padding": null, + "right": null, + "top": null, + "visibility": null, + "width": null + } + }, + "523c02e7168e4463af9859b2a2b945f7": { + "model_module": "@jupyter-widgets/base", + "model_module_version": "2.0.0", + "model_name": "LayoutModel", + "state": { + "_model_module": "@jupyter-widgets/base", + "_model_module_version": "2.0.0", + "_model_name": "LayoutModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/base", + "_view_module_version": "2.0.0", + "_view_name": "LayoutView", + "align_content": null, + "align_items": null, + "align_self": null, + "border_bottom": null, + "border_left": null, + "border_right": null, + "border_top": null, + "bottom": null, + "display": null, + "flex": null, + "flex_flow": null, + "grid_area": null, + "grid_auto_columns": null, + "grid_auto_flow": null, + "grid_auto_rows": null, + "grid_column": null, + "grid_gap": null, + "grid_row": null, + "grid_template_areas": null, + "grid_template_columns": null, + "grid_template_rows": null, + "height": null, + "justify_content": null, + "justify_items": null, + "left": null, + "margin": null, + "max_height": null, + "max_width": null, + "min_height": null, + "min_width": null, + "object_fit": null, + "object_position": null, + "order": null, + "overflow": null, + "padding": null, + "right": null, + "top": null, + "visibility": null, + "width": null + } + }, + "92816b6214464fbeacc423f505253df6": { + "model_module": "@jupyter-widgets/controls", + "model_module_version": "2.0.0", + "model_name": "ProgressStyleModel", + "state": { + "_model_module": "@jupyter-widgets/controls", + "_model_module_version": "2.0.0", + "_model_name": "ProgressStyleModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/base", + "_view_module_version": "2.0.0", + "_view_name": "StyleView", + "bar_color": null, + "description_width": "" + } + }, + "a8e34b28670e42518d5302ec3737a09e": { + "model_module": "@jupyter-widgets/controls", + "model_module_version": "2.0.0", + "model_name": "HTMLModel", + "state": { + "_dom_classes": [], + "_model_module": "@jupyter-widgets/controls", + "_model_module_version": "2.0.0", + "_model_name": "HTMLModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/controls", + "_view_module_version": "2.0.0", + "_view_name": "HTMLView", + "description": "", + "description_allow_html": false, + "layout": "IPY_MODEL_3d977298874a42d1b7432d67c99d5395", + "placeholder": "​", + "style": "IPY_MODEL_e7afd5ff3dec48b993eec540f6f6ea3d", + "tabbable": null, + "tooltip": null, + "value": " 100/100 [00:00<00:00, 958.09it/s]" + } + }, + "b20b85efefdd48eea89d08c6f34c9996": { + "model_module": "@jupyter-widgets/controls", + "model_module_version": "2.0.0", + "model_name": "HTMLStyleModel", + "state": { + "_model_module": "@jupyter-widgets/controls", + "_model_module_version": "2.0.0", + "_model_name": "HTMLStyleModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/base", + "_view_module_version": "2.0.0", + "_view_name": "StyleView", + "background": null, + "description_width": "", + "font_size": null, + "text_color": null + } + }, + "cdb8edf0dc034465a7770e52e980ced6": { + "model_module": "@jupyter-widgets/base", + "model_module_version": "2.0.0", + "model_name": "LayoutModel", + "state": { + "_model_module": "@jupyter-widgets/base", + "_model_module_version": "2.0.0", + "_model_name": "LayoutModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/base", + "_view_module_version": "2.0.0", + "_view_name": "LayoutView", + "align_content": null, + "align_items": null, + "align_self": null, + "border_bottom": null, + "border_left": null, + "border_right": null, + "border_top": null, + "bottom": null, + "display": null, + "flex": null, + "flex_flow": null, + "grid_area": null, + "grid_auto_columns": null, + "grid_auto_flow": null, + "grid_auto_rows": null, + "grid_column": null, + "grid_gap": null, + "grid_row": null, + "grid_template_areas": null, + "grid_template_columns": null, + "grid_template_rows": null, + "height": null, + "justify_content": null, + "justify_items": null, + "left": null, + "margin": null, + "max_height": null, + "max_width": null, + "min_height": null, + "min_width": null, + "object_fit": null, + "object_position": null, + "order": null, + "overflow": null, + "padding": null, + "right": null, + "top": null, + "visibility": null, + "width": null + } + }, + "de683211fe2044c79f27449a3784392f": { + "model_module": "@jupyter-widgets/controls", + "model_module_version": "2.0.0", + "model_name": "HBoxModel", + "state": { + "_dom_classes": [], + "_model_module": "@jupyter-widgets/controls", + "_model_module_version": "2.0.0", + "_model_name": "HBoxModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/controls", + "_view_module_version": "2.0.0", + "_view_name": "HBoxView", + "box_style": "", + "children": [ + "IPY_MODEL_e6c7597d5cef42e2a8c179c23dc66bfa", + "IPY_MODEL_fce367fa747c48c4a66d47e11a0b64f1", + "IPY_MODEL_a8e34b28670e42518d5302ec3737a09e" + ], + "layout": "IPY_MODEL_523c02e7168e4463af9859b2a2b945f7", + "tabbable": null, + "tooltip": null + } + }, + "e6c7597d5cef42e2a8c179c23dc66bfa": { + "model_module": "@jupyter-widgets/controls", + "model_module_version": "2.0.0", + "model_name": "HTMLModel", + "state": { + "_dom_classes": [], + "_model_module": "@jupyter-widgets/controls", + "_model_module_version": "2.0.0", + "_model_name": "HTMLModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/controls", + "_view_module_version": "2.0.0", + "_view_name": "HTMLView", + "description": "", + "description_allow_html": false, + "layout": "IPY_MODEL_0464f9bccf1248feb2ae2081538d7b1d", + "placeholder": "​", + "style": "IPY_MODEL_b20b85efefdd48eea89d08c6f34c9996", + "tabbable": null, + "tooltip": null, + "value": "100%" + } + }, + "e7afd5ff3dec48b993eec540f6f6ea3d": { + "model_module": "@jupyter-widgets/controls", + "model_module_version": "2.0.0", + "model_name": "HTMLStyleModel", + "state": { + "_model_module": "@jupyter-widgets/controls", + "_model_module_version": "2.0.0", + "_model_name": "HTMLStyleModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/base", + "_view_module_version": "2.0.0", + "_view_name": "StyleView", + "background": null, + "description_width": "", + "font_size": null, + "text_color": null + } + }, + "fce367fa747c48c4a66d47e11a0b64f1": { + "model_module": "@jupyter-widgets/controls", + "model_module_version": "2.0.0", + "model_name": "FloatProgressModel", + "state": { + "_dom_classes": [], + "_model_module": "@jupyter-widgets/controls", + "_model_module_version": "2.0.0", + "_model_name": "FloatProgressModel", + "_view_count": null, + "_view_module": "@jupyter-widgets/controls", + "_view_module_version": "2.0.0", + "_view_name": "ProgressView", + "bar_style": "success", + "description": "", + "description_allow_html": false, + "layout": "IPY_MODEL_cdb8edf0dc034465a7770e52e980ced6", + "max": 100, + "min": 0, + "orientation": "horizontal", + "style": "IPY_MODEL_92816b6214464fbeacc423f505253df6", + "tabbable": null, + "tooltip": null, + "value": 100 + } + } + }, + "version_major": 2, + "version_minor": 0 + } + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/examples/single_objective_bayes_opt/bax_tutorial.ipynb b/docs/examples/single_objective_bayes_opt/bax_tutorial.ipynb new file mode 100644 index 0000000..f0b795c --- /dev/null +++ b/docs/examples/single_objective_bayes_opt/bax_tutorial.ipynb @@ -0,0 +1,430 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Basic Optimization using BAX\n", + "In this notebook we demonstrate the use of Xopt to perform Bayesian Algorithm Execution (BAX) as a means of minimizing the output of a simple test function. BAX is a generalization of Bayesian Optimization that seeks to acquire observations that provide our model with maximal information about our property of interest. In this simple example, our property of interest is the minimum function output and its location in input-space. See https://arxiv.org/pdf/2209.04587.pdf for details." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Imports and random seeding for reproducibility" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-07-30T20:40:01.274627800Z", + "start_time": "2024-07-30T20:39:57.849796300Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:55:55.364961Z", + "iopub.status.busy": "2024-09-13T15:55:55.364610Z", + "iopub.status.idle": "2024-09-13T15:55:57.130703Z", + "shell.execute_reply": "2024-09-13T15:55:57.130276Z" + } + }, + "outputs": [], + "source": [ + "import torch\n", + "\n", + "from xopt import Xopt\n", + "from xopt.vocs import VOCS\n", + "from xopt.generators.bayesian.bax_generator import BaxGenerator\n", + "from xopt.generators.bayesian.bax.algorithms import GridOptimize\n", + "from xopt.evaluator import Evaluator\n", + "from xopt.generators.bayesian.bax.visualize import visualize_virtual_objective\n", + "\n", + "import numpy as np\n", + "import random\n", + "\n", + "import os\n", + "import math\n", + "import matplotlib.pyplot as plt\n", + "\n", + "# Ignore all warnings\n", + "import warnings\n", + "\n", + "warnings.filterwarnings(\"ignore\")\n", + "\n", + "\n", + "os.environ[\"KMP_DUPLICATE_LIB_OK\"] = \"True\"\n", + "\n", + "# random seeds for reproducibility\n", + "rand_seed = 2\n", + "\n", + "torch.manual_seed(rand_seed)\n", + "np.random.seed(rand_seed) # only affects initial random observations through Xopt\n", + "random.seed(rand_seed)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Define the test problem\n", + "Here we define a simple optimization problem, where we attempt to minimize the sin\n", + "function in the domian [0,2*pi]. Note that the function used to evaluate the\n", + "objective function takes a dictionary as input and returns a dictionary as the output." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-07-30T20:40:01.289628200Z", + "start_time": "2024-07-30T20:40:01.277626900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:55:57.132763Z", + "iopub.status.busy": "2024-09-13T15:55:57.132536Z", + "iopub.status.idle": "2024-09-13T15:55:57.134879Z", + "shell.execute_reply": "2024-09-13T15:55:57.134579Z" + } + }, + "outputs": [], + "source": [ + "# define variables and function objectives\n", + "vocs = VOCS(\n", + " variables={\"x\": [0, 2 * math.pi]},\n", + " observables=[\"y1\"],\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-07-30T20:40:01.318392200Z", + "start_time": "2024-07-30T20:40:01.291627800Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:55:57.136536Z", + "iopub.status.busy": "2024-09-13T15:55:57.136408Z", + "iopub.status.idle": "2024-09-13T15:55:57.138213Z", + "shell.execute_reply": "2024-09-13T15:55:57.137991Z" + } + }, + "outputs": [], + "source": [ + "# define a test function to optimize\n", + "def sin_function(input_dict):\n", + " return {\"y1\": np.sin(input_dict[\"x\"])}" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Prepare BAX generator for Xopt\n", + "Create a generator that uses the ExpectedInformationGain (InfoBAX) acquisition\n", + "function to perform Bayesian Optimization. Note that we use minimization on a grid,\n", + "so specifying the number of mesh points can negatively impact decision making time\n", + "(especially in higher dimensional feature spaces)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-07-30T20:40:01.322392400Z", + "start_time": "2024-07-30T20:40:01.308880200Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:55:57.139600Z", + "iopub.status.busy": "2024-09-13T15:55:57.139487Z", + "iopub.status.idle": "2024-09-13T15:55:57.141211Z", + "shell.execute_reply": "2024-09-13T15:55:57.140968Z" + } + }, + "outputs": [], + "source": [ + "# Prepare BAX algorithm and generator options\n", + "algorithm = GridOptimize(n_mesh_points=50) # NOTE: default is to minimize\n", + "\n", + "# construct BAX generator\n", + "generator = BaxGenerator(vocs=vocs, algorithm=algorithm)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Create Evaluator and Xopt objects\n", + "Create the Evaluator (which allows Xopt to interface with our test function) and finish constructing our Xopt object." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-07-30T20:40:01.336812700Z", + "start_time": "2024-07-30T20:40:01.323393100Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:55:57.142623Z", + "iopub.status.busy": "2024-09-13T15:55:57.142503Z", + "iopub.status.idle": "2024-09-13T15:55:57.147883Z", + "shell.execute_reply": "2024-09-13T15:55:57.147582Z" + } + }, + "outputs": [], + "source": [ + "# construct evaluator\n", + "evaluator = Evaluator(function=sin_function)\n", + "\n", + "# construct Xopt optimizer\n", + "X = Xopt(evaluator=evaluator, generator=generator, vocs=vocs)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Generate and evaluate initial points\n", + "To begin optimization, we must generate some random initial data points. The first call\n", + "to `X.step()` will generate and evaluate a number of randomly points specified by the\n", + " generator. Note that if we add data to xopt before calling `X.step()` by assigning\n", + " the data to `X.data`, calls to `X.step()` will ignore the random generation and\n", + " proceed to generating points via Bayesian optimization." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-07-30T20:40:01.395027700Z", + "start_time": "2024-07-30T20:40:01.337812700Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:55:57.149353Z", + "iopub.status.busy": "2024-09-13T15:55:57.149264Z", + "iopub.status.idle": "2024-09-13T15:55:57.157170Z", + "shell.execute_reply": "2024-09-13T15:55:57.156926Z" + } + }, + "outputs": [], + "source": [ + "# evaluate initial points\n", + "X.random_evaluate(3)\n", + "\n", + "# inspect the gathered data\n", + "X.data" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "### Define plotting utility\n", + "Define a plotting function that plots the GP model, samples from the GP model, and the\n", + "execution paths (red crosses)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-07-30T20:40:01.398993800Z", + "start_time": "2024-07-30T20:40:01.380025800Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:55:57.179682Z", + "iopub.status.busy": "2024-09-13T15:55:57.179513Z", + "iopub.status.idle": "2024-09-13T15:55:57.185064Z", + "shell.execute_reply": "2024-09-13T15:55:57.184714Z" + } + }, + "outputs": [], + "source": [ + "def plot_bax(X):\n", + " # get the Gaussian process model from the generator\n", + " model = X.generator.train_model()\n", + "\n", + " # get acquisition function from generator\n", + " acq = X.generator.get_acquisition(model)\n", + "\n", + " # calculate model posterior and acquisition function at each test point\n", + " # NOTE: need to add a dimension to the input tensor for evaluating the\n", + " # posterior and another for the acquisition function, see\n", + " # https://botorch.org/docs/batching for details\n", + " # NOTE: we use the `torch.no_grad()` environment to speed up computation by\n", + " # skipping calculations for backpropagation\n", + " with torch.no_grad():\n", + " posterior = model.posterior(test_x.unsqueeze(1))\n", + " acq_val = acq(test_x.reshape(-1, 1, 1))\n", + "\n", + " # get mean function and confidence regions\n", + " mean = posterior.mean\n", + " L, u = posterior.mvn.confidence_region()\n", + "\n", + " # plot model and acquisition function\n", + " fig, ax = plt.subplots(3, 1, sharex=\"all\")\n", + " fig.set_size_inches(8, 6)\n", + "\n", + " # plot model posterior\n", + " ax[0].plot(test_x, mean, label=\"Posterior mean\")\n", + " ax[0].fill_between(test_x, L, u, alpha=0.25, label=\"Posterior confidence region\")\n", + "\n", + " # add data to model plot\n", + " ax[0].plot(X.data[\"x\"], X.data[\"y1\"], \"C1o\", label=\"Training data\")\n", + "\n", + " # plot true function\n", + " true_f = sin_function({\"x\": test_x})[\"y1\"]\n", + " ax[0].plot(test_x, true_f, \"--\", label=\"Ground truth\")\n", + "\n", + " # plot the function samples and their optima found by BAX\n", + " test_points = X.generator.algorithm_results[\"test_points\"]\n", + " posterior_samples = X.generator.algorithm_results[\"posterior_samples\"]\n", + " execution_paths = X.generator.algorithm_results[\"execution_paths\"]\n", + "\n", + " label1 = \"Function Samples\"\n", + " label2 = \"Sample Optima\"\n", + " for i in range(X.generator.algorithm.n_samples):\n", + " (samples,) = ax[1].plot(\n", + " test_points, posterior_samples[i], c=\"C0\", alpha=0.3, label=label1\n", + " )\n", + " ax[1].scatter(\n", + " *execution_paths[i], c=\"r\", marker=\"x\", s=80, label=label2, zorder=10\n", + " )\n", + " label1 = None\n", + " label2 = None\n", + "\n", + " # plot acquisition function\n", + " ax[2].plot(test_x, acq_val.flatten())\n", + "\n", + " ax[0].set_ylabel(\"y1\")\n", + " ax[1].set_ylabel(\"y1\")\n", + " ax[2].set_ylabel(r\"$\\alpha(x)$\")\n", + " ax[2].set_xlabel(\"x\")\n", + "\n", + " return fig, ax" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Do bayesian optimization steps\n", + "To perform optimization we simply call `X.step()` in a loop. This allows us to do\n", + "intermediate tasks in between optimization steps, such as examining the model and\n", + "acquisition function at each step (as we demonstrate here)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-07-30T20:40:11.438033900Z", + "start_time": "2024-07-30T20:40:01.385024100Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:55:57.186686Z", + "iopub.status.busy": "2024-09-13T15:55:57.186547Z", + "iopub.status.idle": "2024-09-13T15:56:01.230192Z", + "shell.execute_reply": "2024-09-13T15:56:01.229853Z" + } + }, + "outputs": [], + "source": [ + "n_steps = 3\n", + "\n", + "# test points for plotting\n", + "test_x = torch.linspace(*X.vocs.bounds.flatten(), 50).double()\n", + "\n", + "for i in range(5):\n", + " # plot model and bax information\n", + " fig, ax = plot_bax(X)\n", + "\n", + " if i == 0:\n", + " ax[0].legend(ncols=2)\n", + " ax[1].legend()\n", + "\n", + " # do the optimization step\n", + " X.step()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-07-30T20:40:11.453033700Z", + "start_time": "2024-07-30T20:40:11.435033200Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:01.231866Z", + "iopub.status.busy": "2024-09-13T15:56:01.231695Z", + "iopub.status.idle": "2024-09-13T15:56:01.235374Z", + "shell.execute_reply": "2024-09-13T15:56:01.235137Z" + } + }, + "outputs": [], + "source": [ + "# access the collected data\n", + "X.data" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-07-30T20:40:11.696033700Z", + "start_time": "2024-07-30T20:40:11.450033600Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:01.236731Z", + "iopub.status.busy": "2024-09-13T15:56:01.236643Z", + "iopub.status.idle": "2024-09-13T15:56:01.319340Z", + "shell.execute_reply": "2024-09-13T15:56:01.319019Z" + } + }, + "outputs": [], + "source": [ + "# plot the virtual objective (which in this case is simply the observable model for y1) via posterior sampling\n", + "\n", + "visualize_virtual_objective(X.generator, n_samples=1000)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/single_objective_bayes_opt/benchmarking.ipynb b/docs/examples/single_objective_bayes_opt/benchmarking.ipynb new file mode 100644 index 0000000..42d34fd --- /dev/null +++ b/docs/examples/single_objective_bayes_opt/benchmarking.ipynb @@ -0,0 +1,329 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Benchmarking" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-26T22:03:09.729462100Z", + "start_time": "2023-10-26T22:03:06.180990700Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:30.955726Z", + "iopub.status.busy": "2024-09-13T15:56:30.955156Z", + "iopub.status.idle": "2024-09-13T15:56:32.687466Z", + "shell.execute_reply": "2024-09-13T15:56:32.687060Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "import matplotlib.pyplot as plt\n", + "import pandas as pd\n", + "import torch\n", + "from copy import deepcopy\n", + "from xopt.generators.bayesian import ExpectedImprovementGenerator\n", + "from xopt.generators.bayesian import BayesianExplorationGenerator\n", + "\n", + "from xopt.vocs import VOCS\n", + "\n", + "# Ignore all warnings\n", + "import warnings\n", + "\n", + "warnings.filterwarnings(\"ignore\")\n", + "\n", + "vocs = VOCS(\n", + " variables={\"x\": [0, 1]},\n", + " objectives={\"y\": \"MAXIMIZE\"},\n", + " constraints={\"c\": [\"LESS_THAN\", 0]},\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-26T22:03:09.924488500Z", + "start_time": "2023-10-26T22:03:09.731462500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:32.689311Z", + "iopub.status.busy": "2024-09-13T15:56:32.689143Z", + "iopub.status.idle": "2024-09-13T15:56:32.772273Z", + "shell.execute_reply": "2024-09-13T15:56:32.772026Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# define test functions\n", + "def y(x):\n", + " return torch.sin(2 * 3.14 * x)\n", + "\n", + "\n", + "def c(x):\n", + " return 10.0 * torch.cos(2 * 3.14 * x + 0.25)\n", + "\n", + "\n", + "test_x = torch.linspace(*torch.tensor(vocs.bounds.flatten()), 100)\n", + "\n", + "# define training data to pass to the generator\n", + "train_x = torch.tensor((0.2, 0.5, 0.6))\n", + "train_y = y(train_x)\n", + "train_c = c(train_x)\n", + "\n", + "data = pd.DataFrame({\"x\": train_x.numpy(), \"y\": train_y.numpy(), \"c\": train_c})\n", + "\n", + "\n", + "def plot_ground_truth():\n", + " fig, ax = plt.subplots()\n", + " ax.plot(test_x, y(test_x), \"--C0\")\n", + " ax.plot(test_x, c(test_x), \"--C1\")\n", + " ax.plot(train_x, train_y, \"oC0\")\n", + " ax.plot(train_x, train_c, \"oC1\")\n", + "\n", + " return ax\n", + "\n", + "\n", + "plot_ground_truth();" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "# Normal Model with Standard transforms and no constraints\n", + "- acquisition function is Expected Improvement" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-26T22:03:10.494462400Z", + "start_time": "2023-10-26T22:03:09.925461800Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:32.793612Z", + "iopub.status.busy": "2024-09-13T15:56:32.793479Z", + "iopub.status.idle": "2024-09-13T15:56:33.235778Z", + "shell.execute_reply": "2024-09-13T15:56:33.235506Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# plot the generator model and acquisition function\n", + "test_vocs = deepcopy(vocs)\n", + "test_vocs.constraints = {}\n", + "generator = ExpectedImprovementGenerator(vocs=test_vocs)\n", + "generator.add_data(data)\n", + "model = generator.train_model()\n", + "fig, ax = generator.visualize_model()" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "# Normal Model with Standard transforms and constraints" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-26T22:03:11.274725200Z", + "start_time": "2023-10-26T22:03:10.496461Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:33.237405Z", + "iopub.status.busy": "2024-09-13T15:56:33.237212Z", + "iopub.status.idle": "2024-09-13T15:56:33.558680Z", + "shell.execute_reply": "2024-09-13T15:56:33.558427Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# plot the generator model and acquisition function\n", + "generator = ExpectedImprovementGenerator(vocs=deepcopy(vocs))\n", + "generator.add_data(data)\n", + "model = generator.train_model()\n", + "fig, ax = generator.visualize_model()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-26T22:03:12.144692900Z", + "start_time": "2023-10-26T22:03:11.276691300Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:33.560357Z", + "iopub.status.busy": "2024-09-13T15:56:33.560246Z", + "iopub.status.idle": "2024-09-13T15:56:33.889156Z", + "shell.execute_reply": "2024-09-13T15:56:33.888888Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# plot the generator model and acquisition function\n", + "tvocs = deepcopy(vocs)\n", + "tvocs.constraints = {\"c\": [\"GREATER_THAN\", 0]}\n", + "\n", + "generator = ExpectedImprovementGenerator(vocs=tvocs)\n", + "generator.add_data(data)\n", + "model = generator.train_model()\n", + "fig, ax = generator.visualize_model()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-26T22:03:38.264419300Z", + "start_time": "2023-10-26T22:03:37.355381700Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:33.891272Z", + "iopub.status.busy": "2024-09-13T15:56:33.891143Z", + "iopub.status.idle": "2024-09-13T15:56:34.212847Z", + "shell.execute_reply": "2024-09-13T15:56:34.212564Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# plot the generator model and acquisition function\n", + "test_vocs = deepcopy(vocs)\n", + "test_vocs.objectives = {}\n", + "test_vocs.observables = [\"y\"]\n", + "\n", + "generator = BayesianExplorationGenerator(vocs=test_vocs)\n", + "generator.add_data(data)\n", + "model = generator.train_model()\n", + "fig, ax = generator.visualize_model()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-26T22:04:02.301053Z", + "start_time": "2023-10-26T22:04:01.536716800Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:34.214620Z", + "iopub.status.busy": "2024-09-13T15:56:34.214499Z", + "iopub.status.idle": "2024-09-13T15:56:34.534405Z", + "shell.execute_reply": "2024-09-13T15:56:34.534129Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "generator = BayesianExplorationGenerator(vocs=test_vocs)\n", + "\n", + "data = pd.DataFrame(\n", + " {\"x\": train_x.numpy(), \"y\": train_y.numpy(), \"c\": torch.zeros_like(train_y).numpy()}\n", + ")\n", + "generator.add_data(data)\n", + "model = generator.train_model()\n", + "fig, ax = generator.visualize_model()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-10-26T22:04:02.767052200Z", + "start_time": "2023-10-26T22:04:02.303051200Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:34.536114Z", + "iopub.status.busy": "2024-09-13T15:56:34.536006Z", + "iopub.status.idle": "2024-09-13T15:56:34.711473Z", + "shell.execute_reply": "2024-09-13T15:56:34.711171Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "test_vocs = deepcopy(test_vocs)\n", + "test_vocs.constraints = {}\n", + "generator = BayesianExplorationGenerator(vocs=test_vocs)\n", + "\n", + "data = pd.DataFrame(\n", + " {\"x\": train_x.numpy(), \"y\": train_y.numpy(), \"c\": torch.zeros_like(train_y).numpy()}\n", + ")\n", + "generator.add_data(data)\n", + "model = generator.train_model()\n", + "fig, ax = generator.visualize_model()" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/single_objective_bayes_opt/bo_tutorial.ipynb b/docs/examples/single_objective_bayes_opt/bo_tutorial.ipynb new file mode 100644 index 0000000..c4979cb --- /dev/null +++ b/docs/examples/single_objective_bayes_opt/bo_tutorial.ipynb @@ -0,0 +1,360 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Basic Bayesian Optimization\n", + "In this tutorial we demonstrate the use of Xopt to preform Bayesian Optimization on a\n", + " simple test problem." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Define the test problem\n", + "Here we define a simple optimization problem, where we attempt to minimize the sin\n", + "function in the domian [0,2*pi]. Note that the function used to evaluate the\n", + "objective function takes a dictionary as input and returns a dictionary as the output." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-04-21T14:39:38.756460Z", + "start_time": "2023-04-21T14:39:36.916454Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:40.504418Z", + "iopub.status.busy": "2024-09-13T15:54:40.503940Z", + "iopub.status.idle": "2024-09-13T15:54:42.299260Z", + "shell.execute_reply": "2024-09-13T15:54:42.298941Z" + } + }, + "outputs": [], + "source": [ + "from xopt.vocs import VOCS\n", + "from xopt.evaluator import Evaluator\n", + "from xopt.generators.bayesian import UpperConfidenceBoundGenerator\n", + "from xopt import Xopt\n", + "import torch\n", + "import matplotlib.pyplot as plt\n", + "import math\n", + "import numpy as np\n", + "\n", + "# define variables and function objectives\n", + "vocs = VOCS(\n", + " variables={\"x\": [0, 2 * math.pi]},\n", + " objectives={\"f\": \"MINIMIZE\"},\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-04-21T14:39:38.760199Z", + "start_time": "2023-04-21T14:39:38.757155Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:42.301322Z", + "iopub.status.busy": "2024-09-13T15:54:42.301113Z", + "iopub.status.idle": "2024-09-13T15:54:42.303076Z", + "shell.execute_reply": "2024-09-13T15:54:42.302830Z" + } + }, + "outputs": [], + "source": [ + "# define a test function to optimize\n", + "def sin_function(input_dict):\n", + " return {\"f\": np.sin(input_dict[\"x\"])}" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Create Xopt objects\n", + "Create the evaluator to evaluate our test function and create a generator that uses\n", + "the Upper Confidence Bound acquisition function to perform Bayesian Optimization." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-04-21T14:39:38.769546Z", + "start_time": "2023-04-21T14:39:38.765875Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:42.304489Z", + "iopub.status.busy": "2024-09-13T15:54:42.304389Z", + "iopub.status.idle": "2024-09-13T15:54:42.309045Z", + "shell.execute_reply": "2024-09-13T15:54:42.308828Z" + } + }, + "outputs": [], + "source": [ + "evaluator = Evaluator(function=sin_function)\n", + "generator = UpperConfidenceBoundGenerator(vocs=vocs)\n", + "X = Xopt(evaluator=evaluator, generator=generator, vocs=vocs)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Generate and evaluate initial points\n", + "To begin optimization, we must generate some random initial data points. The first call\n", + "to `X.step()` will generate and evaluate a number of randomly points specified by the\n", + " generator. Note that if we add data to xopt before calling `X.step()` by assigning\n", + " the data to `X.data`, calls to `X.step()` will ignore the random generation and\n", + " proceed to generating points via Bayesian optimization." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-04-21T14:39:38.780529Z", + "start_time": "2023-04-21T14:39:38.770010Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:42.310443Z", + "iopub.status.busy": "2024-09-13T15:54:42.310351Z", + "iopub.status.idle": "2024-09-13T15:54:42.317339Z", + "shell.execute_reply": "2024-09-13T15:54:42.317108Z" + } + }, + "outputs": [], + "source": [ + "# call X.random_evaluate() to generate + evaluate 3 initial points\n", + "X.random_evaluate(2)\n", + "\n", + "# inspect the gathered data\n", + "X.data" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Do bayesian optimization steps\n", + "To perform optimization we simply call `X.step()` in a loop. This allows us to do\n", + "intermediate tasks in between optimization steps, such as examining the model and\n", + "acquisition function at each step (as we demonstrate here)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-04-21T14:39:40.645385Z", + "start_time": "2023-04-21T14:39:38.783110Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:42.337828Z", + "iopub.status.busy": "2024-09-13T15:54:42.337698Z", + "iopub.status.idle": "2024-09-13T15:54:43.800699Z", + "shell.execute_reply": "2024-09-13T15:54:43.800325Z" + } + }, + "outputs": [], + "source": [ + "n_steps = 5\n", + "\n", + "# test points for plotting\n", + "test_x = torch.linspace(*X.vocs.bounds.flatten(), 50).double()\n", + "\n", + "for i in range(n_steps):\n", + " # get the Gaussian process model from the generator\n", + " model = X.generator.train_model()\n", + "\n", + " # get acquisition function from generator\n", + " acq = X.generator.get_acquisition(model)\n", + "\n", + " # calculate model posterior and acquisition function at each test point\n", + " # NOTE: need to add a dimension to the input tensor for evaluating the\n", + " # posterior and another for the acquisition function, see\n", + " # https://botorch.org/docs/batching for details\n", + " # NOTE: we use the `torch.no_grad()` environment to speed up computation by\n", + " # skipping calculations for backpropagation\n", + " with torch.no_grad():\n", + " posterior = model.posterior(test_x.unsqueeze(1))\n", + " acq_val = acq(test_x.reshape(-1, 1, 1))\n", + "\n", + " # get mean function and confidence regions\n", + " mean = posterior.mean\n", + " L, u = posterior.mvn.confidence_region()\n", + "\n", + " # plot model and acquisition function\n", + " fig, ax = plt.subplots(2, 1, sharex=\"all\")\n", + "\n", + " # plot model posterior\n", + " ax[0].plot(test_x, mean, label=\"Posterior mean\")\n", + " ax[0].fill_between(test_x, L, u, alpha=0.25, label=\"Posterior confidence region\")\n", + "\n", + " # add data to model plot\n", + " ax[0].plot(X.data[\"x\"], X.data[\"f\"], \"C1o\", label=\"Training data\")\n", + "\n", + " # plot true function\n", + " true_f = sin_function({\"x\": test_x})[\"f\"]\n", + " ax[0].plot(test_x, true_f, \"--\", label=\"Ground truth\")\n", + "\n", + " # add legend\n", + " ax[0].legend()\n", + "\n", + " # plot acquisition function\n", + " ax[1].plot(test_x, acq_val.flatten())\n", + "\n", + " ax[0].set_ylabel(\"f\")\n", + " ax[1].set_ylabel(r\"$\\alpha(x)$\")\n", + " ax[1].set_xlabel(\"x\")\n", + "\n", + " # do the optimization step\n", + " X.step()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-04-21T14:39:40.650703Z", + "start_time": "2023-04-21T14:39:40.648118Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:43.802317Z", + "iopub.status.busy": "2024-09-13T15:54:43.802139Z", + "iopub.status.idle": "2024-09-13T15:54:43.805912Z", + "shell.execute_reply": "2024-09-13T15:54:43.805655Z" + } + }, + "outputs": [], + "source": [ + "# access the collected data\n", + "X.data" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Getting the optimization result\n", + "To get the best point (without evaluating it) we ask the generator to\n", + "predict the optimum based on the posterior mean." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-04-21T14:39:41.043509Z", + "start_time": "2023-04-21T14:39:40.651174Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:43.807331Z", + "iopub.status.busy": "2024-09-13T15:54:43.807236Z", + "iopub.status.idle": "2024-09-13T15:54:43.851867Z", + "shell.execute_reply": "2024-09-13T15:54:43.851631Z" + } + }, + "outputs": [], + "source": [ + "X.generator.get_optimum()" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Customizing optimization\n", + "Each generator has a set of options that can be modified to effect optimization behavior" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-04-21T14:39:41.046912Z", + "start_time": "2023-04-21T14:39:41.044438Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:43.853410Z", + "iopub.status.busy": "2024-09-13T15:54:43.853319Z", + "iopub.status.idle": "2024-09-13T15:54:43.856576Z", + "shell.execute_reply": "2024-09-13T15:54:43.856264Z" + } + }, + "outputs": [], + "source": [ + "X.generator.dict()" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/single_objective_bayes_opt/constrained_bo_tutorial.ipynb b/docs/examples/single_objective_bayes_opt/constrained_bo_tutorial.ipynb new file mode 100644 index 0000000..57f8406 --- /dev/null +++ b/docs/examples/single_objective_bayes_opt/constrained_bo_tutorial.ipynb @@ -0,0 +1,279 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Constrained Bayesian Optimization\n", + "In this tutorial we demonstrate the use of Xopt to perform Bayesian Optimization on a simple test problem subject to a single constraint." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Define the test problem\n", + "Here we define a simple optimization problem, where we attempt to minimize the sin\n", + "function in the domian [0,2*pi], subject to a cos constraining function." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2025-01-07T20:55:57.751261500Z", + "start_time": "2025-01-07T20:55:53.793271Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:22.206398Z", + "iopub.status.busy": "2024-09-13T15:56:22.205993Z", + "iopub.status.idle": "2024-09-13T15:56:23.774772Z", + "shell.execute_reply": "2024-09-13T15:56:23.774246Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "from xopt.evaluator import Evaluator\n", + "from xopt.generators.bayesian import ExpectedImprovementGenerator\n", + "from xopt import Xopt\n", + "from xopt.vocs import VOCS\n", + "\n", + "import time\n", + "import math\n", + "import numpy as np\n", + "\n", + "# Ignore all warnings\n", + "import warnings\n", + "\n", + "warnings.filterwarnings(\"ignore\")\n", + "\n", + "# define variables, function objective and constraining function\n", + "vocs = VOCS(\n", + " variables={\"x\": [0, 2 * math.pi]},\n", + " objectives={\"f\": \"MINIMIZE\"},\n", + " constraints={\"c\": [\"LESS_THAN\", 0]},\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2025-01-07T20:55:57.766139300Z", + "start_time": "2025-01-07T20:55:57.738794400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:23.776855Z", + "iopub.status.busy": "2024-09-13T15:56:23.776613Z", + "iopub.status.idle": "2024-09-13T15:56:23.778792Z", + "shell.execute_reply": "2024-09-13T15:56:23.778518Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# define a test function to optimize\n", + "\n", + "\n", + "def test_function(input_dict):\n", + " return {\"f\": np.sin(input_dict[\"x\"]), \"c\": np.cos(input_dict[\"x\"])}" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Create Xopt objects\n", + "Create the evaluator to evaluate our test function and create a generator that uses\n", + "the Expected Improvement acquisition function to perform Bayesian Optimization." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2025-01-07T20:55:57.766682400Z", + "start_time": "2025-01-07T20:55:57.751261500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:23.780319Z", + "iopub.status.busy": "2024-09-13T15:56:23.780210Z", + "iopub.status.idle": "2024-09-13T15:56:23.785380Z", + "shell.execute_reply": "2024-09-13T15:56:23.785094Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "evaluator = Evaluator(function=test_function)\n", + "generator = ExpectedImprovementGenerator(vocs=vocs)\n", + "X = Xopt(evaluator=evaluator, generator=generator, vocs=vocs)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Generate and evaluate initial points\n", + "To begin optimization, we must generate some random initial data points. The first call\n", + "to `X.step()` will generate and evaluate a number of randomly points specified by the\n", + " generator. Note that if we add data to xopt before calling `X.step()` by assigning\n", + " the data to `X.data`, calls to `X.step()` will ignore the random generation and\n", + " proceed to generating points via Bayesian optimization." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2025-01-07T20:55:57.767710800Z", + "start_time": "2025-01-07T20:55:57.766139300Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:23.786867Z", + "iopub.status.busy": "2024-09-13T15:56:23.786774Z", + "iopub.status.idle": "2024-09-13T15:56:23.849752Z", + "shell.execute_reply": "2024-09-13T15:56:23.849497Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# call X.random_evaluate(n_samples) to generate + evaluate initial points\n", + "X.random_evaluate(n_samples=2)\n", + "\n", + "# inspect the gathered data\n", + "X.data" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Do bayesian optimization steps\n", + "To perform optimization we simply call `X.step()` in a loop. This allows us to do\n", + "intermediate tasks in between optimization steps, such as examining the model and\n", + "acquisition function at each step (as we demonstrate here)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2025-01-07T20:57:47.398979200Z", + "start_time": "2025-01-07T20:57:37.742437900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:23.870983Z", + "iopub.status.busy": "2024-09-13T15:56:23.870838Z", + "iopub.status.idle": "2024-09-13T15:56:28.798647Z", + "shell.execute_reply": "2024-09-13T15:56:28.798342Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "n_steps = 5\n", + "\n", + "# test points for plotting\n", + "test_x = np.linspace(*X.vocs.bounds.flatten(), 50)\n", + "\n", + "for i in range(n_steps):\n", + " start = time.perf_counter()\n", + " model = X.generator.train_model()\n", + " fig, ax = X.generator.visualize_model(n_grid=100)\n", + " print(time.perf_counter() - start)\n", + "\n", + " # add ground truth functions to plots\n", + " out = test_function({\"x\": test_x})\n", + " ax[0, 0].plot(test_x, out[\"f\"], \"C0-.\")\n", + " ax[1, 0].plot(test_x, out[\"c\"], \"C2-.\")\n", + "\n", + " # do the optimization step\n", + " X.step()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:56:28.800492Z", + "iopub.status.busy": "2024-09-13T15:56:28.800330Z", + "iopub.status.idle": "2024-09-13T15:56:28.804449Z", + "shell.execute_reply": "2024-09-13T15:56:28.804220Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# access the collected data\n", + "X.data" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/single_objective_bayes_opt/custom_model.ipynb b/docs/examples/single_objective_bayes_opt/custom_model.ipynb new file mode 100644 index 0000000..6e7dfd9 --- /dev/null +++ b/docs/examples/single_objective_bayes_opt/custom_model.ipynb @@ -0,0 +1,327 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "# Custom GP modeling for BO" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:55:44.392214Z", + "iopub.status.busy": "2024-09-13T15:55:44.391949Z", + "iopub.status.idle": "2024-09-13T15:55:46.132932Z", + "shell.execute_reply": "2024-09-13T15:55:46.132592Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "from xopt.generators.bayesian.expected_improvement import ExpectedImprovementGenerator\n", + "from xopt.generators.bayesian.models.standard import StandardModelConstructor\n", + "from gpytorch.kernels import PeriodicKernel, ScaleKernel\n", + "\n", + "import matplotlib.pyplot as plt\n", + "import pandas as pd\n", + "import torch\n", + "from xopt.vocs import VOCS\n", + "\n", + "# Ignore all warnings\n", + "import warnings\n", + "\n", + "warnings.filterwarnings(\"ignore\")\n", + "\n", + "my_vocs = VOCS(\n", + " variables={\"x\": [0, 1]},\n", + " objectives={\"y\": \"MAXIMIZE\"},\n", + " constraints={\"c\": [\"LESS_THAN\", 0]},\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:55:46.134708Z", + "iopub.status.busy": "2024-09-13T15:55:46.134564Z", + "iopub.status.idle": "2024-09-13T15:55:46.211537Z", + "shell.execute_reply": "2024-09-13T15:55:46.211305Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# define test functions\n", + "def y(x):\n", + " return torch.sin(2 * 3.14 * x)\n", + "\n", + "\n", + "def c(x):\n", + " return 5.0 * torch.cos(2 * 3.14 * x + 0.25)\n", + "\n", + "\n", + "test_x = torch.linspace(*torch.tensor(my_vocs.bounds.flatten()), 100)\n", + "\n", + "# define training data to pass to the generator\n", + "train_x = torch.tensor((0.2, 0.5, 0.6))\n", + "train_y = y(train_x)\n", + "train_c = c(train_x)\n", + "\n", + "training_data = pd.DataFrame({\"x\": train_x.numpy(), \"y\": train_y.numpy(), \"c\": train_c})\n", + "\n", + "\n", + "def plot_ground_truth():\n", + " fig, ax = plt.subplots()\n", + " ax.plot(test_x, y(test_x), \"--C0\")\n", + " ax.plot(test_x, c(test_x), \"--C1\")\n", + " ax.plot(train_x, train_y, \"oC0\")\n", + " ax.plot(train_x, train_c, \"oC1\")\n", + "\n", + " return ax\n", + "\n", + "\n", + "plot_ground_truth()" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "# Custom kernel definition\n", + "In this example we know that the target optimization function is periodic, so it\n", + "makes sense to use a periodic kernel for the GP model with no noise. Here we define a\n", + "function to create that model." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:55:46.213082Z", + "iopub.status.busy": "2024-09-13T15:55:46.212973Z", + "iopub.status.idle": "2024-09-13T15:55:46.364491Z", + "shell.execute_reply": "2024-09-13T15:55:46.364170Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# note the creation of options beforehand\n", + "# specify a periodic kernel for each output (objectives and constraints)\n", + "covar_module = {\"y\": ScaleKernel(PeriodicKernel())}\n", + "gp_constructor = StandardModelConstructor(covar_modules=covar_module)\n", + "generator = ExpectedImprovementGenerator(vocs=my_vocs, gp_constructor=gp_constructor)\n", + "generator" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:55:46.366115Z", + "iopub.status.busy": "2024-09-13T15:55:46.365935Z", + "iopub.status.idle": "2024-09-13T15:55:47.115670Z", + "shell.execute_reply": "2024-09-13T15:55:47.115409Z" + } + }, + "outputs": [], + "source": [ + "# view custom model from data\n", + "generator.add_data(training_data)\n", + "model = generator.train_model()\n", + "\n", + "fig, ax = generator.visualize_model(n_grid=len(test_x))\n", + "# plot ground truth\n", + "ax[0, 0].plot(test_x, y(test_x), \"C0-.\")\n", + "ax[1, 0].plot(test_x, c(test_x), \"C2-.\");" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:55:47.117629Z", + "iopub.status.busy": "2024-09-13T15:55:47.117531Z", + "iopub.status.idle": "2024-09-13T15:55:47.120092Z", + "shell.execute_reply": "2024-09-13T15:55:47.119863Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "model" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:55:47.121444Z", + "iopub.status.busy": "2024-09-13T15:55:47.121358Z", + "iopub.status.idle": "2024-09-13T15:55:47.579026Z", + "shell.execute_reply": "2024-09-13T15:55:47.578738Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# get the next point from the generator\n", + "generator.generate(1)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Custom prior mean function\n", + "Here we assume we have some knowledge of the ground truth function, which we can take\n", + " advantage of to speed up optimization. This \"prior mean\" function is specified by a\n", + " pytorch module." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:55:47.580651Z", + "iopub.status.busy": "2024-09-13T15:55:47.580533Z", + "iopub.status.idle": "2024-09-13T15:55:47.582620Z", + "shell.execute_reply": "2024-09-13T15:55:47.582408Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "class ConstraintPrior(torch.nn.Module):\n", + " def forward(self, X):\n", + " return c(X).squeeze(dim=-1)\n", + "\n", + "\n", + "gp_constructor = StandardModelConstructor(mean_modules={\"c\": ConstraintPrior()})\n", + "generator = ExpectedImprovementGenerator(\n", + " vocs=my_vocs,\n", + " gp_constructor=gp_constructor,\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:55:47.584014Z", + "iopub.status.busy": "2024-09-13T15:55:47.583912Z", + "iopub.status.idle": "2024-09-13T15:55:47.906696Z", + "shell.execute_reply": "2024-09-13T15:55:47.906433Z" + } + }, + "outputs": [], + "source": [ + "# view custom model from data\n", + "generator.add_data(training_data)\n", + "model = generator.train_model()\n", + "\n", + "fig, ax = generator.visualize_model(n_grid=len(test_x))\n", + "# plot ground truth\n", + "ax[0, 0].plot(test_x, y(test_x), \"C0-.\")\n", + "ax[1, 0].plot(test_x, c(test_x), \"C2-.\");" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:55:47.908422Z", + "iopub.status.busy": "2024-09-13T15:55:47.908299Z", + "iopub.status.idle": "2024-09-13T15:55:47.910794Z", + "shell.execute_reply": "2024-09-13T15:55:47.910537Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "model" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:55:47.912149Z", + "iopub.status.busy": "2024-09-13T15:55:47.912052Z", + "iopub.status.idle": "2024-09-13T15:55:47.916181Z", + "shell.execute_reply": "2024-09-13T15:55:47.915789Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "list(model.named_parameters())" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/single_objective_bayes_opt/custom_objective.ipynb b/docs/examples/single_objective_bayes_opt/custom_objective.ipynb new file mode 100644 index 0000000..ad48690 --- /dev/null +++ b/docs/examples/single_objective_bayes_opt/custom_objective.ipynb @@ -0,0 +1,278 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Bayesian Optimization with Custom Objectives\n", + "In this tutorial we demonstrate the use of Xopt to preform Bayesian Optimization on\n", + "custom objectives. In this case, we develop models of individual components of the\n", + "objective function and combine samples from these models to calculate predicted\n", + "objective values.\n", + "\n", + "In this example we try to maximize the objective function\n", + "$$f(g_1(x),g_2(x)) = \\min(g_1(x), g_2(x))$$ where $g_1(x) = (x-0.5)^2$ and $g_2(x) =\n", + "(x - 2)^2$.\n" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Define the test problem" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-06-07T19:11:05.338818500Z", + "start_time": "2024-06-07T19:11:03.007948400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:42.362599Z", + "iopub.status.busy": "2024-09-13T15:56:42.362284Z", + "iopub.status.idle": "2024-09-13T15:56:43.963796Z", + "shell.execute_reply": "2024-09-13T15:56:43.963288Z" + } + }, + "outputs": [], + "source": [ + "from xopt.vocs import VOCS\n", + "\n", + "import torch\n", + "\n", + "from xopt.evaluator import Evaluator\n", + "from xopt.generators.bayesian import ExpectedImprovementGenerator\n", + "from xopt import Xopt\n", + "from xopt.generators.bayesian.objectives import CustomXoptObjective\n", + "from torch import Tensor\n", + "from typing import Optional\n", + "\n", + "\n", + "# define variables and function objectives\n", + "vocs = VOCS(variables={\"x\": [0.0, 2.0]}, observables=[\"g1\", \"g2\"])" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-06-07T19:11:05.398577600Z", + "start_time": "2024-06-07T19:11:05.395358400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:43.966070Z", + "iopub.status.busy": "2024-09-13T15:56:43.965821Z", + "iopub.status.idle": "2024-09-13T15:56:43.968101Z", + "shell.execute_reply": "2024-09-13T15:56:43.967794Z" + } + }, + "outputs": [], + "source": [ + "# define a test function to optimize\n", + "\n", + "\n", + "def sin_function(input_dict):\n", + " return {\"g1\": (input_dict[\"x\"]) ** 2, \"g2\": (input_dict[\"x\"] - 2.0) ** 2}" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Create Xopt objects\n", + "Create the evaluator to evaluate our test function and create a generator that uses\n", + "the Upper Confidence Bound acquisition function to perform Bayesian Optimization." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-06-07T19:11:13.023338300Z", + "start_time": "2024-06-07T19:11:05.403548700Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:43.969973Z", + "iopub.status.busy": "2024-09-13T15:56:43.969806Z", + "iopub.status.idle": "2024-09-13T15:56:47.066052Z", + "shell.execute_reply": "2024-09-13T15:56:47.065779Z" + } + }, + "outputs": [], + "source": [ + "class MyObjective(CustomXoptObjective):\n", + " def forward(self, samples: Tensor, X: Optional[Tensor] = None) -> Tensor:\n", + " return torch.min(\n", + " samples[..., self.vocs.output_names.index(\"g1\")],\n", + " samples[..., self.vocs.output_names.index(\"g2\")],\n", + " )\n", + "\n", + "\n", + "evaluator = Evaluator(function=sin_function)\n", + "generator = ExpectedImprovementGenerator(\n", + " vocs=vocs,\n", + " custom_objective=MyObjective(vocs),\n", + ")\n", + "X = Xopt(evaluator=evaluator, generator=generator, vocs=vocs)\n", + "print(X)\n", + "\n", + "X.random_evaluate(2)\n", + "\n", + "n_steps = 5\n", + "\n", + "# test points for plotting\n", + "test_x = torch.linspace(*X.vocs.bounds.flatten(), 50).double()\n", + "\n", + "for i in range(n_steps):\n", + " # get the Gaussian process model from the generator\n", + " model = X.generator.train_model()\n", + "\n", + " X.generator.visualize_model()\n", + "\n", + " # do the optimization step\n", + " X.step()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-06-07T19:11:13.065201200Z", + "start_time": "2024-06-07T19:11:13.025339800Z" + } + }, + "outputs": [], + "source": [] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-06-07T19:11:13.070201400Z", + "start_time": "2024-06-07T19:11:13.054349Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:47.067639Z", + "iopub.status.busy": "2024-09-13T15:56:47.067467Z", + "iopub.status.idle": "2024-09-13T15:56:47.072846Z", + "shell.execute_reply": "2024-09-13T15:56:47.072630Z" + } + }, + "outputs": [], + "source": [ + "# access the collected data\n", + "X.data" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Getting the optimization result\n", + "To get the best point (without evaluating it) we ask the generator to\n", + "predict the optimum based on the posterior mean." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-06-07T19:11:13.894203Z", + "start_time": "2024-06-07T19:11:13.072204900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:47.074184Z", + "iopub.status.busy": "2024-09-13T15:56:47.074098Z", + "iopub.status.idle": "2024-09-13T15:56:47.388879Z", + "shell.execute_reply": "2024-09-13T15:56:47.388566Z" + } + }, + "outputs": [], + "source": [ + "X.generator.get_optimum()" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Customizing optimization\n", + "Each generator has a set of options that can be modified to effect optimization behavior" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-06-07T19:11:13.968067600Z", + "start_time": "2024-06-07T19:11:13.896722400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:47.390453Z", + "iopub.status.busy": "2024-09-13T15:56:47.390342Z", + "iopub.status.idle": "2024-09-13T15:56:47.393596Z", + "shell.execute_reply": "2024-09-13T15:56:47.393324Z" + } + }, + "outputs": [], + "source": [ + "X.generator.dict()" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/single_objective_bayes_opt/fixed_features.ipynb b/docs/examples/single_objective_bayes_opt/fixed_features.ipynb new file mode 100644 index 0000000..01dc240 --- /dev/null +++ b/docs/examples/single_objective_bayes_opt/fixed_features.ipynb @@ -0,0 +1,361 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "# Bayesian optimization with fixed features\n", + "In some contexts a variable/feature needs to be fixed during optimization. However, we\n", + "can leverage previous measurements near the fixed variable value to potentially\n", + "jump-start optimization using observed model covariances established by the GP kernel\n", + ". In this example, we start with a number of random observations in 2D input space\n", + "and then proceed with BO at a fixed value for one of the variables. This notebook\n", + "uses the 2D Rosenbrock test function as an example." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-04-23T14:30:02.733046Z", + "start_time": "2024-04-23T14:29:59.284072800Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:55:10.932053Z", + "iopub.status.busy": "2024-09-13T15:55:10.931840Z", + "iopub.status.idle": "2024-09-13T15:55:12.675171Z", + "shell.execute_reply": "2024-09-13T15:55:12.674838Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# set values if testing\n", + "import os\n", + "\n", + "from xopt.generators.bayesian.visualize import plot_model_prediction\n", + "from xopt import Xopt, Evaluator\n", + "from xopt.generators.bayesian import UpperConfidenceBoundGenerator\n", + "from xopt.resources.test_functions.rosenbrock import (\n", + " evaluate_rosenbrock,\n", + " make_rosenbrock_vocs,\n", + ")\n", + "\n", + "# Ignore all warnings\n", + "import warnings\n", + "\n", + "warnings.filterwarnings(\"ignore\")\n", + "\n", + "\n", + "SMOKE_TEST = os.environ.get(\"SMOKE_TEST\")\n", + "NUM_MC_SAMPLES = 1 if SMOKE_TEST else 128\n", + "NUM_RESTARTS = 1 if SMOKE_TEST else 20\n", + "\n", + "# make rosenbrock function vocs in 2D\n", + "vocs = make_rosenbrock_vocs(2)\n", + "\n", + "# define a fixed value for the BO generator\n", + "fixed_features = {\"x0\": -1.0}\n", + "generator = UpperConfidenceBoundGenerator(vocs=vocs, fixed_features=fixed_features)\n", + "generator.numerical_optimizer.n_restarts = NUM_RESTARTS\n", + "generator.n_monte_carlo_samples = NUM_MC_SAMPLES\n", + "\n", + "evaluator = Evaluator(function=evaluate_rosenbrock)\n", + "\n", + "X = Xopt(generator=generator, evaluator=evaluator, vocs=vocs)\n", + "X" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Generate some initial random samples in 2D space" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-04-23T14:30:02.748083700Z", + "start_time": "2024-04-23T14:30:02.735488400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:55:12.696548Z", + "iopub.status.busy": "2024-09-13T15:55:12.696219Z", + "iopub.status.idle": "2024-09-13T15:55:12.704733Z", + "shell.execute_reply": "2024-09-13T15:55:12.704452Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "X.random_evaluate(10)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Run BO steps with fixed features" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-04-23T14:30:03.894045900Z", + "start_time": "2024-04-23T14:30:02.751046400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:55:12.706413Z", + "iopub.status.busy": "2024-09-13T15:55:12.706293Z", + "iopub.status.idle": "2024-09-13T15:55:13.268838Z", + "shell.execute_reply": "2024-09-13T15:55:13.268516Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "for i in range(5):\n", + " X.step()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-04-23T14:30:03.909044600Z", + "start_time": "2024-04-23T14:30:03.896046400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:55:13.270560Z", + "iopub.status.busy": "2024-09-13T15:55:13.270428Z", + "iopub.status.idle": "2024-09-13T15:55:13.274756Z", + "shell.execute_reply": "2024-09-13T15:55:13.274532Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "X.data" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Visualize model and evaluations\n", + "Note that for the BO samples, they all are on the line $x_0=-1$" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-04-23T14:30:04.947068400Z", + "start_time": "2024-04-23T14:30:03.915044900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:55:13.276113Z", + "iopub.status.busy": "2024-09-13T15:55:13.276022Z", + "iopub.status.idle": "2024-09-13T15:55:13.661335Z", + "shell.execute_reply": "2024-09-13T15:55:13.661053Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "ax = plot_model_prediction(\n", + " model=X.generator.model,\n", + " vocs=X.vocs,\n", + " data=X.data,\n", + " show_samples=False,\n", + " n_grid=100,\n", + ")\n", + "ax.plot(\n", + " *X.data[[\"x0\", \"x1\"]].to_numpy()[:10].T, \"+C1\", label=\"random samples\", zorder=10\n", + ")\n", + "ax.plot(*X.data[[\"x0\", \"x1\"]].to_numpy()[10:].T, \"+C3\", label=\"GP samples\", zorder=10)\n", + "ax.axvline(-1.0, ls=\"--\")\n", + "ax.legend();" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Run with fixed feature that is not in vocs\n", + "We can also run fixed features where the fixed variable is not listed in vocs, as\n", + "long as the generator data contains data corresponding to the fixed feature name. To\n", + "satisfy this requirements we add the data from the last optimization run." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-04-23T14:30:04.962067400Z", + "start_time": "2024-04-23T14:30:04.948069800Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:55:13.663054Z", + "iopub.status.busy": "2024-09-13T15:55:13.662884Z", + "iopub.status.idle": "2024-09-13T15:55:13.664825Z", + "shell.execute_reply": "2024-09-13T15:55:13.664561Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# make rosenbrock function vocs in 2-D but remove the `x0` name (set to a fixed\n", + "# feature in the next cell)\n", + "vocs = make_rosenbrock_vocs(2)\n", + "vocs.variables = {\"x1\": [-2.0, 2.0]}" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-04-23T14:30:04.995067700Z", + "start_time": "2024-04-23T14:30:04.964067300Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:55:13.666096Z", + "iopub.status.busy": "2024-09-13T15:55:13.666007Z", + "iopub.status.idle": "2024-09-13T15:55:13.668895Z", + "shell.execute_reply": "2024-09-13T15:55:13.668681Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# define a fixed value for the BO generator\n", + "fixed_features = {\"x0\": -1.0}\n", + "generator = UpperConfidenceBoundGenerator(vocs=vocs, fixed_features=fixed_features)\n", + "generator.numerical_optimizer.n_restarts = NUM_RESTARTS\n", + "generator.n_monte_carlo_samples = NUM_MC_SAMPLES\n", + "\n", + "evaluator = Evaluator(function=evaluate_rosenbrock)\n", + "\n", + "X2 = Xopt(generator=generator, evaluator=evaluator, vocs=vocs)\n", + "X2.add_data(X.data)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-04-23T14:30:05.217066800Z", + "start_time": "2024-04-23T14:30:04.978069700Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:55:13.670154Z", + "iopub.status.busy": "2024-09-13T15:55:13.670055Z", + "iopub.status.idle": "2024-09-13T15:55:13.751792Z", + "shell.execute_reply": "2024-09-13T15:55:13.751511Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# run an optimization step\n", + "X2.step()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-04-23T14:30:05.231068700Z", + "start_time": "2024-04-23T14:30:05.218066400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:55:13.753432Z", + "iopub.status.busy": "2024-09-13T15:55:13.753336Z", + "iopub.status.idle": "2024-09-13T15:55:13.757642Z", + "shell.execute_reply": "2024-09-13T15:55:13.757403Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "X2.data" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.9" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/single_objective_bayes_opt/hessian_kernel.ipynb b/docs/examples/single_objective_bayes_opt/hessian_kernel.ipynb new file mode 100644 index 0000000..7bbfba9 --- /dev/null +++ b/docs/examples/single_objective_bayes_opt/hessian_kernel.ipynb @@ -0,0 +1,174 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "# Bayesian Optimization with a Hessian\n", + "Here we demonstrate the use of a Hessian matrix to estimate the kernel." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Specifiying generator options\n", + "We start with the generator defaults and add a hessian kernel to the model. This also\n", + " requires specifying that we will not normalize inputs to the GP model. Note: this\n", + " can potentially mess up training of other hyperparameters." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-01-30T18:13:12.173225200Z", + "start_time": "2024-01-30T18:13:08.389096400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:36.873445Z", + "iopub.status.busy": "2024-09-13T15:56:36.873193Z", + "iopub.status.idle": "2024-09-13T15:56:38.531203Z", + "shell.execute_reply": "2024-09-13T15:56:38.530904Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# set values if testing\n", + "import os\n", + "import torch\n", + "from copy import deepcopy\n", + "from xopt import Xopt, Evaluator\n", + "from xopt.generators.bayesian import UpperConfidenceBoundGenerator\n", + "from xopt.generators.bayesian.models.standard import StandardModelConstructor\n", + "from xopt.generators.bayesian.custom_botorch.hessian_kernel import HessianRBF\n", + "from gpytorch.kernels import ScaleKernel\n", + "from xopt.resources.test_functions.tnk import evaluate_TNK, tnk_vocs\n", + "\n", + "# Ignore all warnings\n", + "import warnings\n", + "\n", + "warnings.filterwarnings(\"ignore\")\n", + "\n", + "SMOKE_TEST = os.environ.get(\"SMOKE_TEST\")\n", + "NUM_MC_SAMPLES = 1 if SMOKE_TEST else 128\n", + "NUM_RESTARTS = 1 if SMOKE_TEST else 20\n", + "\n", + "vocs = deepcopy(tnk_vocs)\n", + "vocs.objectives = {\"y2\": \"MINIMIZE\"}\n", + "\n", + "# define a custom kernel and create the model constructor\n", + "hessian_matrix = torch.tensor([[1, -0.8], [-0.8, 1]]).double()\n", + "kernel = ScaleKernel(HessianRBF(hessian_matrix))\n", + "gp_constructor = StandardModelConstructor(covar_modules={\"y2\": kernel})\n", + "\n", + "\n", + "generator = UpperConfidenceBoundGenerator(vocs=vocs, gp_constructor=gp_constructor)\n", + "generator.numerical_optimizer.n_restarts = NUM_RESTARTS\n", + "generator.n_monte_carlo_samples = NUM_MC_SAMPLES\n", + "\n", + "evaluator = Evaluator(function=evaluate_TNK)\n", + "\n", + "X = Xopt(generator=generator, evaluator=evaluator, vocs=vocs)\n", + "X" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Evaluate explict points and view model\n", + "We start with evaluating 2 points that we know satisfy the constraints. Note the\n", + "cross correlations between x1 and x2 due to the Hessian kernel." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-01-30T18:13:47.228144100Z", + "start_time": "2024-01-30T18:13:44.084105500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:38.552397Z", + "iopub.status.busy": "2024-09-13T15:56:38.552210Z", + "iopub.status.idle": "2024-09-13T15:56:40.162265Z", + "shell.execute_reply": "2024-09-13T15:56:40.161946Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "X.evaluate_data({\"x1\": [1.0, 0.75], \"x2\": [1.0, 2.0]})\n", + "X.generator.train_model()\n", + "fig, ax = X.generator.visualize_model(show_feasibility=True, n_grid=100)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-01-30T18:13:16.075775100Z", + "start_time": "2024-01-30T18:13:16.040771500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:40.165128Z", + "iopub.status.busy": "2024-09-13T15:56:40.164983Z", + "iopub.status.idle": "2024-09-13T15:56:40.170771Z", + "shell.execute_reply": "2024-09-13T15:56:40.170544Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "X.data" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/single_objective_bayes_opt/heteroskedastic_noise_tutorial.ipynb b/docs/examples/single_objective_bayes_opt/heteroskedastic_noise_tutorial.ipynb new file mode 100644 index 0000000..b9fbcdc --- /dev/null +++ b/docs/examples/single_objective_bayes_opt/heteroskedastic_noise_tutorial.ipynb @@ -0,0 +1,362 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Bayesian Optimization with Heteroskedastic Noise GP Modeling\n", + "In this tutorial we demonstrate the use of Xopt to preform Bayesian Optimization on a\n", + " simple test problem. The problem exibits non-uniform (heteroskedastic) noise which\n", + " we account for in the GP model. This requires explicit specification of the\n", + " measurement variance." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Define the test problem\n", + "Here we define a simple optimization problem, where we attempt to minimize the sin\n", + "function in the domian [0,2*pi]. Note that the function used to evaluate the\n", + "objective function takes a dictionary as input and returns a dictionary as the output." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-07T21:28:39.921005100Z", + "start_time": "2023-09-07T21:28:24.293120800Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:49.730834Z", + "iopub.status.busy": "2024-09-13T15:56:49.730533Z", + "iopub.status.idle": "2024-09-13T15:56:51.293807Z", + "shell.execute_reply": "2024-09-13T15:56:51.293378Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "from xopt.vocs import VOCS\n", + "from xopt.evaluator import Evaluator\n", + "from xopt.generators.bayesian import UpperConfidenceBoundGenerator\n", + "from xopt import Xopt\n", + "import math\n", + "import numpy as np\n", + "import torch\n", + "\n", + "# define variables and function objectives\n", + "vocs = VOCS(\n", + " variables={\"x\": [0, 2 * math.pi]},\n", + " objectives={\"f\": \"MINIMIZE\"},\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Specifying measurement variance\n", + "We specify variance in the objective function by appending `_var` to it. This info\n", + "will collected by the model constructor to make a heteroskedastic model." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-07T21:28:39.935173300Z", + "start_time": "2023-09-07T21:28:39.924004400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:51.295804Z", + "iopub.status.busy": "2024-09-13T15:56:51.295584Z", + "iopub.status.idle": "2024-09-13T15:56:51.297605Z", + "shell.execute_reply": "2024-09-13T15:56:51.297393Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# define a test function to optimize\n", + "# the test function also returns an estimation of the variance, which is\n", + "# used to create a Heteroskedastic noise model for the gp\n", + "\n", + "\n", + "def sin_function(input_dict):\n", + " return {\"f\": np.sin(input_dict[\"x\"]), \"f_var\": 0.001 * input_dict[\"x\"]}" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Create Xopt objects\n", + "Create the evaluator to evaluate our test function and create a generator that uses\n", + "the Upper Confidence Bound acquisition function to perform Bayesian Optimization." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-07T21:28:39.952164900Z", + "start_time": "2023-09-07T21:28:39.939194600Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:51.299041Z", + "iopub.status.busy": "2024-09-13T15:56:51.298940Z", + "iopub.status.idle": "2024-09-13T15:56:51.303791Z", + "shell.execute_reply": "2024-09-13T15:56:51.303548Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "evaluator = Evaluator(function=sin_function)\n", + "generator = UpperConfidenceBoundGenerator(vocs=vocs)\n", + "X = Xopt(evaluator=evaluator, generator=generator, vocs=vocs)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Generate and evaluate initial points\n", + "To begin optimization, we must generate some random initial data points. The first call\n", + "to `X.step()` will generate and evaluate a number of randomly points specified by the\n", + " generator. Note that if we add data to xopt before calling `X.step()` by assigning\n", + " the data to `X.data`, calls to `X.step()` will ignore the random generation and\n", + " proceed to generating points via Bayesian optimization." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-07T21:28:39.999187800Z", + "start_time": "2023-09-07T21:28:39.953166Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:51.305166Z", + "iopub.status.busy": "2024-09-13T15:56:51.305077Z", + "iopub.status.idle": "2024-09-13T15:56:51.372282Z", + "shell.execute_reply": "2024-09-13T15:56:51.371871Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# call X.random_evaluate() to generate + evaluate 3 initial points\n", + "X.random_evaluate(4)\n", + "\n", + "# inspect the gathered data\n", + "X.data" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Do bayesian optimization steps\n", + "To perform optimization we simply call `X.step()` in a loop. This allows us to do\n", + "intermediate tasks in between optimization steps, such as examining the model and\n", + "acquisition function at each step (as we demonstrate here)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:56:51.394471Z", + "iopub.status.busy": "2024-09-13T15:56:51.394306Z", + "iopub.status.idle": "2024-09-13T15:56:55.128341Z", + "shell.execute_reply": "2024-09-13T15:56:55.128036Z" + } + }, + "outputs": [], + "source": [ + "n_steps = 5\n", + "\n", + "# test points for plotting\n", + "test_x = torch.linspace(*X.vocs.bounds.flatten(), 50).double()\n", + "\n", + "for i in range(n_steps):\n", + " # get the Gaussian process model from the generator\n", + " model = X.generator.train_model()\n", + "\n", + " # visualize model\n", + " fig, ax = X.generator.visualize_model(n_grid=len(test_x))\n", + "\n", + " # plot true function\n", + " true_f = sin_function({\"x\": test_x})[\"f\"]\n", + " ax[0, 0].plot(test_x, true_f, \"C1--\")\n", + "\n", + " # do the optimization step\n", + " X.step()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-07T21:28:51.486309800Z", + "start_time": "2023-09-07T21:28:51.468312900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:55.129917Z", + "iopub.status.busy": "2024-09-13T15:56:55.129742Z", + "iopub.status.idle": "2024-09-13T15:56:55.134195Z", + "shell.execute_reply": "2024-09-13T15:56:55.133941Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# access the collected data\n", + "X.data" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Getting the optimization result\n", + "To get the best point (without evaluating it) we ask the generator to\n", + "predict the optimum based on the posterior mean." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-07T21:28:51.561309500Z", + "start_time": "2023-09-07T21:28:51.483311900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:55.135637Z", + "iopub.status.busy": "2024-09-13T15:56:55.135552Z", + "iopub.status.idle": "2024-09-13T15:56:55.162709Z", + "shell.execute_reply": "2024-09-13T15:56:55.162466Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "X.generator.get_optimum()" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Customizing optimization\n", + "Each generator has a set of options that can be modified to effect optimization behavior" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-07T21:28:51.586309700Z", + "start_time": "2023-09-07T21:28:51.562311500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:55.164214Z", + "iopub.status.busy": "2024-09-13T15:56:55.164125Z", + "iopub.status.idle": "2024-09-13T15:56:55.167266Z", + "shell.execute_reply": "2024-09-13T15:56:55.167035Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "X.generator.dict()" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/single_objective_bayes_opt/interpolate_tutorial.ipynb b/docs/examples/single_objective_bayes_opt/interpolate_tutorial.ipynb new file mode 100644 index 0000000..3ec93a1 --- /dev/null +++ b/docs/examples/single_objective_bayes_opt/interpolate_tutorial.ipynb @@ -0,0 +1,340 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Bayesian Optimization w/ Interpolated Samples\n", + "In some situations, the process of evaluating objectives and constraints\n", + "consumes fewer resources compared to the computational demands associated\n", + "with Bayesian Optimization (BO) decision-making. Particularly, when\n", + "making subtle changes to parameters during optimization, the cost of\n", + "assessing objectives becomes notably more affordable.\n", + "\n", + "Consider a practical example: the optimization of magnet parameters in an\n", + "accelerator with the goal of either minimizing the beam spot size on a\n", + "screen or maximizing the Free Electron Laser (FEL) pulse energy. In such\n", + "cases, where adjustments to accelerator parameters are frequent, it proves\n", + "beneficial to augment the dataset by implementing multiple smaller changes\n", + "to the parameters. These adjustments are followed by quick measurements of\n", + "the objective in between the parameter changes guided by BO.\n", + "\n", + "This approach, although introducing a slight slowdown to the BO process\n", + "due to the addition of extra training points, it will expedite\n", + "convergence for most problems. It offers a more efficient alternative compared to the\n", + "strategy of measuring the same points multiple times in noisy environments.\n", + "The rationale here is that the exploration of a broader parameter space\n", + "through numerous smaller changes enhances the overall understanding of\n", + "the system's behavior, potentially leading to a more efficient and\n", + "effective optimization process.\n", + "\n", + "NOTE: This only works for serialized problems.\n", + "\n", + "WARNING: The interpolated points may violate constraints! Do not use this feature in\n", + "problems where safety is critical." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Define the test problem\n", + "Here we define a simple optimization problem, where we attempt to minimize the sphere\n", + " function." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-11-18T21:45:33.751558100Z", + "start_time": "2023-11-18T21:45:31.381879Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:46.023291Z", + "iopub.status.busy": "2024-09-13T15:54:46.023005Z", + "iopub.status.idle": "2024-09-13T15:54:47.479491Z", + "shell.execute_reply": "2024-09-13T15:54:47.479086Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "from xopt.vocs import VOCS\n", + "from xopt.evaluator import Evaluator\n", + "from xopt.generators.bayesian import ExpectedImprovementGenerator\n", + "from xopt import Xopt\n", + "\n", + "# define variables and function objectives\n", + "vocs = VOCS(\n", + " variables={\"x1\": [-1, 1], \"x2\": [-1, 1]},\n", + " objectives={\"f\": \"MINIMIZE\"},\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-11-18T21:45:33.765546400Z", + "start_time": "2023-11-18T21:45:33.753560100Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:47.481445Z", + "iopub.status.busy": "2024-09-13T15:54:47.481204Z", + "iopub.status.idle": "2024-09-13T15:54:47.483361Z", + "shell.execute_reply": "2024-09-13T15:54:47.483100Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# define a test function to optimize\n", + "\n", + "\n", + "def sphere_function(input_dict):\n", + " return {\"f\": input_dict[\"x1\"] ** 2 + input_dict[\"x2\"] ** 2}" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Create Xopt objects\n", + "Create the evaluator to evaluate our test function and create a generator that uses\n", + "the Upper Confidence Bound acquisition function to perform Bayesian Optimization. We\n", + "additionally specify `n_interpolate_points` to be non-zero such that the generator\n", + "proposes interpolated points during generation." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-11-18T21:45:34.728144600Z", + "start_time": "2023-11-18T21:45:33.767547200Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:47.484885Z", + "iopub.status.busy": "2024-09-13T15:54:47.484774Z", + "iopub.status.idle": "2024-09-13T15:54:47.489934Z", + "shell.execute_reply": "2024-09-13T15:54:47.489693Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# define a generator that uses 5 interpolation points during sampling\n", + "generator = ExpectedImprovementGenerator(vocs=vocs, n_interpolate_points=5)\n", + "generator.gp_constructor.use_low_noise_prior = True\n", + "\n", + "\n", + "evaluator = Evaluator(function=sphere_function)\n", + "X = Xopt(evaluator=evaluator, generator=generator, vocs=vocs)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Generate and evaluate initial points\n", + "To begin optimization, we must generate some random initial data points. The first call\n", + "to `X.step()` will generate and evaluate a number of randomly points specified by the\n", + " generator. Note that if we add data to xopt before calling `X.step()` by assigning\n", + " the data to `X.data`, calls to `X.step()` will ignore the random generation and\n", + " proceed to generating points via Bayesian optimization." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-11-18T21:45:34.771145400Z", + "start_time": "2023-11-18T21:45:34.729146100Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:47.491291Z", + "iopub.status.busy": "2024-09-13T15:54:47.491210Z", + "iopub.status.idle": "2024-09-13T15:54:47.550723Z", + "shell.execute_reply": "2024-09-13T15:54:47.550314Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# call X.random_evaluate() to generate + evaluate initial points\n", + "X.random_evaluate(2)\n", + "\n", + "# inspect the gathered data\n", + "X.data" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Do bayesian optimization steps\n", + "To perform optimization we simply call `X.step()` in a loop. This allows us to do\n", + "intermediate tasks in between optimization steps, such as examining the model and\n", + "acquisition function at each step (as we demonstrate here)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-11-18T21:45:42.637209400Z", + "start_time": "2023-11-18T21:45:34.762146600Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:47.571375Z", + "iopub.status.busy": "2024-09-13T15:54:47.571234Z", + "iopub.status.idle": "2024-09-13T15:54:51.014558Z", + "shell.execute_reply": "2024-09-13T15:54:51.014298Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "X.generator.train_model()\n", + "X.generator.visualize_model(n_grid=50)\n", + "\n", + "n_steps = 5\n", + "for i in range(n_steps):\n", + " print(i)\n", + " # do the optimization step\n", + " X.step()\n", + "\n", + " # train the model and visualize\n", + " X.generator.train_model()\n", + " fig, ax = X.generator.visualize_model(n_grid=50)\n", + "\n", + " # add the ground truth minimum location\n", + " for a in ax.flatten()[:-1]:\n", + " a.plot(0, 0, \"x\", c=\"red\", ms=10)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-11-18T21:45:42.652179200Z", + "start_time": "2023-11-18T21:45:42.634209700Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:51.016157Z", + "iopub.status.busy": "2024-09-13T15:54:51.015990Z", + "iopub.status.idle": "2024-09-13T15:54:51.021195Z", + "shell.execute_reply": "2024-09-13T15:54:51.020958Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# access the collected data\n", + "X.data" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Getting the optimization result\n", + "To get the best point (without evaluating it) we ask the generator to\n", + "predict the optimum based on the posterior mean." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-11-18T21:45:42.760178900Z", + "start_time": "2023-11-18T21:45:42.649210Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:51.022662Z", + "iopub.status.busy": "2024-09-13T15:54:51.022555Z", + "iopub.status.idle": "2024-09-13T15:54:51.038185Z", + "shell.execute_reply": "2024-09-13T15:54:51.037920Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "X.generator.get_optimum()" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/single_objective_bayes_opt/multi_fidelity_simple.ipynb b/docs/examples/single_objective_bayes_opt/multi_fidelity_simple.ipynb new file mode 100644 index 0000000..d923cfe --- /dev/null +++ b/docs/examples/single_objective_bayes_opt/multi_fidelity_simple.ipynb @@ -0,0 +1,405 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "# Multi-fidelity BO\n", + "Here we demonstrate how Multi-Fidelity Bayesian Optimization can be used to reduce\n", + "the computational cost of optimization by using lower fidelity surrogate models. The\n", + "goal is to learn functional dependance of the objective on input variables at low\n", + "fidelities (which are cheap to compute) and use that information to quickly find the\n", + "best objective value at higher fidelities (which are more expensive to compute). This\n", + "assumes that there is some learnable correlation between the objective values at\n", + "different fidelities.\n", + "\n", + "Xopt implements the MOMF (https://botorch.org/tutorials/Multi_objective_multi_fidelity_BO)\n", + "algorithm which can be used to solve both single (this notebook) and multi-objective\n", + "(see multi-objective BO section) multi-fidelity problems. Under the hood this\n", + "algorithm attempts to solve a multi-objective optimization problem, where one\n", + "objective is the function objective and the other is a simple fidelity objective,\n", + "weighted by the ```cost_function``` of evaluating the objective at a given fidelity." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T20:56:37.715486400Z", + "start_time": "2023-09-06T20:56:34.287048500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:53.299994Z", + "iopub.status.busy": "2024-09-13T15:54:53.299702Z", + "iopub.status.idle": "2024-09-13T15:54:55.104406Z", + "shell.execute_reply": "2024-09-13T15:54:55.104054Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "from xopt.generators.bayesian import MultiFidelityGenerator\n", + "from xopt import Evaluator, Xopt\n", + "from xopt import VOCS\n", + "import os\n", + "\n", + "import matplotlib.pyplot as plt\n", + "import numpy as np\n", + "import math\n", + "\n", + "import pandas as pd\n", + "\n", + "\n", + "# Ignore all warnings\n", + "import warnings\n", + "\n", + "warnings.filterwarnings(\"ignore\")\n", + "\n", + "SMOKE_TEST = os.environ.get(\"SMOKE_TEST\")\n", + "N_MC_SAMPLES = 1 if SMOKE_TEST else 128\n", + "N_RESTARTS = 1 if SMOKE_TEST else 20\n", + "\n", + "\n", + "def test_function(input_dict):\n", + " x = input_dict[\"x\"]\n", + " s = input_dict[\"s\"]\n", + " return {\"f\": np.sin(x + (1.0 - s)) * np.exp((-s + 1) / 2)}\n", + "\n", + "\n", + "# define vocs\n", + "\n", + "\n", + "vocs = VOCS(\n", + " variables={\n", + " \"x\": [0, 2 * math.pi],\n", + " },\n", + " objectives={\"f\": \"MINIMIZE\"},\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## plot the test function in input + fidelity space\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T20:56:37.926455800Z", + "start_time": "2023-09-06T20:56:37.717426100Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:55.106249Z", + "iopub.status.busy": "2024-09-13T15:54:55.106085Z", + "iopub.status.idle": "2024-09-13T15:54:55.204449Z", + "shell.execute_reply": "2024-09-13T15:54:55.204188Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "test_x = np.linspace(*vocs.bounds, 1000)\n", + "fidelities = [0.0, 0.5, 1.0]\n", + "\n", + "fig, ax = plt.subplots()\n", + "for ele in fidelities:\n", + " f = test_function({\"x\": test_x, \"s\": ele})[\"f\"]\n", + " ax.plot(test_x, f, label=f\"s:{ele}\")\n", + "\n", + "ax.legend()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T20:56:37.956437100Z", + "start_time": "2023-09-06T20:56:37.938740600Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:55.205929Z", + "iopub.status.busy": "2024-09-13T15:54:55.205819Z", + "iopub.status.idle": "2024-09-13T15:54:55.213771Z", + "shell.execute_reply": "2024-09-13T15:54:55.213524Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# create xopt object\n", + "# get and modify default generator options\n", + "generator = MultiFidelityGenerator(vocs=vocs)\n", + "\n", + "# specify a custom cost function based on the fidelity parameter\n", + "generator.cost_function = lambda s: s + 0.001\n", + "\n", + "generator.numerical_optimizer.n_restarts = N_RESTARTS\n", + "generator.n_monte_carlo_samples = N_MC_SAMPLES\n", + "\n", + "# pass options to the generator\n", + "evaluator = Evaluator(function=test_function)\n", + "\n", + "X = Xopt(vocs=vocs, generator=generator, evaluator=evaluator)\n", + "X" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T20:56:38.014457500Z", + "start_time": "2023-09-06T20:56:37.958428200Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:55.215114Z", + "iopub.status.busy": "2024-09-13T15:54:55.215029Z", + "iopub.status.idle": "2024-09-13T15:54:55.221521Z", + "shell.execute_reply": "2024-09-13T15:54:55.221288Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# evaluate initial points at mixed fidelities to seed optimization\n", + "X.evaluate_data(\n", + " pd.DataFrame({\"x\": [math.pi / 4, math.pi / 2.0, math.pi], \"s\": [0.0, 0.25, 0.0]})\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T20:56:38.044457900Z", + "start_time": "2023-09-06T20:56:37.988488800Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:55.222934Z", + "iopub.status.busy": "2024-09-13T15:54:55.222847Z", + "iopub.status.idle": "2024-09-13T15:54:55.226410Z", + "shell.execute_reply": "2024-09-13T15:54:55.226157Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# get the total cost of previous observations based on the cost function\n", + "X.generator.calculate_total_cost()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T20:57:03.359514100Z", + "start_time": "2023-09-06T20:56:38.003459300Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:54:55.227712Z", + "iopub.status.busy": "2024-09-13T15:54:55.227634Z", + "iopub.status.idle": "2024-09-13T15:55:07.587383Z", + "shell.execute_reply": "2024-09-13T15:55:07.587046Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# run optimization until the cost budget is exhausted\n", + "# we subtract one unit to make sure we don't go over our eval budget\n", + "budget = 10\n", + "while X.generator.calculate_total_cost() < budget - 1:\n", + " X.step()\n", + " print(\n", + " f\"n_samples: {len(X.data)} \"\n", + " f\"budget used: {X.generator.calculate_total_cost():.4} \"\n", + " f\"hypervolume: {X.generator.calculate_hypervolume():.4}\"\n", + " )" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T20:57:03.374517700Z", + "start_time": "2023-09-06T20:57:03.360514500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:55:07.589480Z", + "iopub.status.busy": "2024-09-13T15:55:07.589294Z", + "iopub.status.idle": "2024-09-13T15:55:07.593868Z", + "shell.execute_reply": "2024-09-13T15:55:07.593600Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "X.data" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Plot the model prediction and acquisition function inside the optimization space" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:55:07.595261Z", + "iopub.status.busy": "2024-09-13T15:55:07.595169Z", + "iopub.status.idle": "2024-09-13T15:55:08.375196Z", + "shell.execute_reply": "2024-09-13T15:55:08.374740Z" + } + }, + "outputs": [], + "source": [ + "fig, ax = X.generator.visualize_model()" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Plot the Pareto front" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T20:57:04.728516600Z", + "start_time": "2023-09-06T20:57:04.588518700Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:55:08.377272Z", + "iopub.status.busy": "2024-09-13T15:55:08.377169Z", + "iopub.status.idle": "2024-09-13T15:55:08.456231Z", + "shell.execute_reply": "2024-09-13T15:55:08.455749Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "X.data.plot(x=\"f\", y=\"s\", style=\"o-\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T20:57:04.748515900Z", + "start_time": "2023-09-06T20:57:04.728516600Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:55:08.458039Z", + "iopub.status.busy": "2024-09-13T15:55:08.457920Z", + "iopub.status.idle": "2024-09-13T15:55:08.462314Z", + "shell.execute_reply": "2024-09-13T15:55:08.462030Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "X.data" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2023-09-06T20:57:04.959513900Z", + "start_time": "2023-09-06T20:57:04.744515900Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:55:08.463848Z", + "iopub.status.busy": "2024-09-13T15:55:08.463748Z", + "iopub.status.idle": "2024-09-13T15:55:08.526992Z", + "shell.execute_reply": "2024-09-13T15:55:08.526656Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# get optimal value at max fidelity, note that the actual maximum is 4.71\n", + "X.generator.get_optimum().to_dict()" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/single_objective_bayes_opt/noisy_bo_tutorial.ipynb b/docs/examples/single_objective_bayes_opt/noisy_bo_tutorial.ipynb new file mode 100644 index 0000000..846f826 --- /dev/null +++ b/docs/examples/single_objective_bayes_opt/noisy_bo_tutorial.ipynb @@ -0,0 +1,360 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Basic Bayesian Optimization\n", + "In this tutorial we demonstrate the use of Xopt to preform Bayesian Optimization on a\n", + " simple test problem." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Define the test problem\n", + "Here we define a simple optimization problem, where we attempt to minimize the sin\n", + "function in the domian [0,2*pi]. Note that the function used to evaluate the\n", + "objective function takes a dictionary as input and returns a dictionary as the output." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2025-01-07T20:49:46.118951500Z", + "start_time": "2025-01-07T20:49:42.123425200Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:55:50.083190Z", + "iopub.status.busy": "2024-09-13T15:55:50.082843Z", + "iopub.status.idle": "2024-09-13T15:55:51.596445Z", + "shell.execute_reply": "2024-09-13T15:55:51.596131Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "import torch\n", + "\n", + "from xopt.evaluator import Evaluator\n", + "from xopt.generators.bayesian import UpperConfidenceBoundGenerator\n", + "from xopt.generators.bayesian.models.standard import StandardModelConstructor\n", + "from xopt import Xopt\n", + "\n", + "from xopt.vocs import VOCS\n", + "\n", + "import numpy as np\n", + "import math\n", + "\n", + "# define variables and function objectives\n", + "vocs = VOCS(\n", + " variables={\"x\": [0, 2 * math.pi]},\n", + " objectives={\"f\": \"MINIMIZE\"},\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2025-01-07T20:49:46.123953400Z", + "start_time": "2025-01-07T20:49:46.121373300Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:55:51.598253Z", + "iopub.status.busy": "2024-09-13T15:55:51.598093Z", + "iopub.status.idle": "2024-09-13T15:55:51.600089Z", + "shell.execute_reply": "2024-09-13T15:55:51.599835Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# define a test function to optimize\n", + "def sin_function(input_dict):\n", + " # return multiple noisy measurements\n", + " return {\n", + " \"f\": np.sin(input_dict[\"x\"]) + 0.5 * np.random.randn(5),\n", + " \"dummy\": np.random.randn(5),\n", + " }" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Create Xopt objects\n", + "Create the evaluator to evaluate our test function and create a generator that uses\n", + "the Upper Confidence Bound acquisition function to perform Bayesian Optimization." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2025-01-07T20:49:46.137486900Z", + "start_time": "2025-01-07T20:49:46.125473400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:55:51.601542Z", + "iopub.status.busy": "2024-09-13T15:55:51.601443Z", + "iopub.status.idle": "2024-09-13T15:55:51.605824Z", + "shell.execute_reply": "2024-09-13T15:55:51.605620Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "evaluator = Evaluator(function=sin_function)\n", + "gp_constructor = StandardModelConstructor(use_low_noise_prior=False)\n", + "generator = UpperConfidenceBoundGenerator(vocs=vocs, gp_constructor=gp_constructor)\n", + "X = Xopt(evaluator=evaluator, generator=generator, vocs=vocs)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Generate and evaluate initial points\n", + "To begin optimization, we must generate some random initial data points. The first call\n", + "to `X.step()` will generate and evaluate a number of randomly points specified by the\n", + " generator. Note that if we add data to xopt before calling `X.step()` by assigning\n", + " the data to `X.data`, calls to `X.step()` will ignore the random generation and\n", + " proceed to generating points via Bayesian optimization." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2025-01-07T20:49:46.162503700Z", + "start_time": "2025-01-07T20:49:46.138488Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:55:51.607170Z", + "iopub.status.busy": "2024-09-13T15:55:51.607083Z", + "iopub.status.idle": "2024-09-13T15:55:51.616050Z", + "shell.execute_reply": "2024-09-13T15:55:51.615821Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# call X.random_evaluate() to generate + evaluate 3 initial points\n", + "X.random_evaluate(2)\n", + "\n", + "# inspect the gathered data\n", + "X.data" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Do bayesian optimization steps\n", + "To perform optimization we simply call `X.step()` in a loop. This allows us to do\n", + "intermediate tasks in between optimization steps, such as examining the model and\n", + "acquisition function at each step (as we demonstrate here)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2025-01-07T20:53:34.584075700Z", + "start_time": "2025-01-07T20:53:31.873077Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:55:51.637303Z", + "iopub.status.busy": "2024-09-13T15:55:51.637164Z", + "iopub.status.idle": "2024-09-13T15:55:53.170688Z", + "shell.execute_reply": "2024-09-13T15:55:53.170435Z" + } + }, + "outputs": [], + "source": [ + "n_steps = 5\n", + "\n", + "# test points for plotting\n", + "test_x = torch.linspace(*X.vocs.bounds.flatten(), 50).double()\n", + "\n", + "for i in range(n_steps):\n", + " # get the Gaussian process model from the generator\n", + " model = X.generator.train_model()\n", + "\n", + " # visualize model\n", + " fig, ax = X.generator.visualize_model(n_grid=len(test_x))\n", + "\n", + " # plot true function\n", + " true_f = torch.sin(test_x)\n", + " ax[0, 0].plot(test_x, true_f, \"C1--\")\n", + "\n", + " # do the optimization step\n", + " X.step()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2025-01-07T20:54:35.973123Z", + "start_time": "2025-01-07T20:54:35.949124200Z" + } + }, + "outputs": [], + "source": [ + "ax[0]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "start_time": "2025-01-07T20:49:47.635533400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:55:53.172228Z", + "iopub.status.busy": "2024-09-13T15:55:53.172059Z", + "iopub.status.idle": "2024-09-13T15:55:53.176984Z", + "shell.execute_reply": "2024-09-13T15:55:53.176754Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "# access the collected data\n", + "X.data" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Getting the optimization result\n", + "To get the best point (without evaluating it) we ask the generator to\n", + "predict the optimum based on the posterior mean." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:55:53.178345Z", + "iopub.status.busy": "2024-09-13T15:55:53.178263Z", + "iopub.status.idle": "2024-09-13T15:55:53.203298Z", + "shell.execute_reply": "2024-09-13T15:55:53.203027Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "X.generator.get_optimum()" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Customizing optimization\n", + "Each generator has a set of options that can be modified to effect optimization behavior" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:55:53.204877Z", + "iopub.status.busy": "2024-09-13T15:55:53.204764Z", + "iopub.status.idle": "2024-09-13T15:55:53.207688Z", + "shell.execute_reply": "2024-09-13T15:55:53.207436Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "X.generator.dict()" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/single_objective_bayes_opt/time_dependent_bo.ipynb b/docs/examples/single_objective_bayes_opt/time_dependent_bo.ipynb new file mode 100644 index 0000000..a7333d2 --- /dev/null +++ b/docs/examples/single_objective_bayes_opt/time_dependent_bo.ipynb @@ -0,0 +1,421 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "collapsed": false + }, + "source": [ + "# Time dependent Bayesian Optimization\n", + "\n", + "In this example we demonstrate time dependent optimization. In this case we are not\n", + "only interested in finding an optimum point in input space, but also maintain the\n", + "ideal point over time." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# set values if testing\n", + "import os\n", + "import time\n", + "import warnings\n", + "import torch\n", + "from matplotlib import pyplot as plt\n", + "from tqdm import trange\n", + "from xopt.generators.bayesian import TDUpperConfidenceBoundGenerator\n", + "from xopt.vocs import VOCS\n", + "from xopt.evaluator import Evaluator\n", + "from xopt import Xopt\n", + "\n", + "SMOKE_TEST = os.environ.get(\"SMOKE_TEST\")\n", + "N_MC_SAMPLES = 1 if SMOKE_TEST else 128\n", + "NUM_RESTARTS = 1 if SMOKE_TEST else 20\n", + "N_STEPS = 1 if SMOKE_TEST else 250\n", + "warnings.filterwarnings(\"ignore\")" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false + }, + "source": [ + "## Time dependent test problem\n", + "Optimization is carried out over a single variable `x`. The test function is a simple\n", + " quadratic, with a minimum location that drifts and changes as a function of time `t`." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false + }, + "source": [ + "Define test functions" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:55:17.650035Z", + "iopub.status.busy": "2024-09-13T15:55:17.649856Z", + "iopub.status.idle": "2024-09-13T15:55:17.659060Z", + "shell.execute_reply": "2024-09-13T15:55:17.658810Z" + } + }, + "outputs": [], + "source": [ + "# location of time dependent minimum\n", + "def k(t_):\n", + " return torch.where(\n", + " t_ < 50, 0.25 * torch.sin(t_ * 6 / 10.0) + 0.1e-2 * t_, -1.5e-2 * (t_ - 50.0)\n", + " )\n", + "\n", + "\n", + "# define function in time and position space\n", + "def g(x_, t_):\n", + " return (x_ - k(t_)) ** 2\n", + "\n", + "\n", + "# create callable function for Xopt\n", + "def f(inputs):\n", + " x_ = inputs[\"x\"]\n", + " current_time = time.time()\n", + " t_ = current_time - start_time\n", + " y_ = g(x_, torch.tensor(t_))\n", + "\n", + " return {\"y\": float(y_), \"time\": float(current_time)}" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false + }, + "source": [ + "## Define Xopt objects including optimization algorithm" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "variables = {\"x\": [-1, 1]}\n", + "objectives = {\"y\": \"MINIMIZE\"}\n", + "\n", + "vocs = VOCS(variables=variables, objectives=objectives)\n", + "\n", + "evaluator = Evaluator(function=f)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false + }, + "source": [ + "## Run optimization" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:55:17.679779Z", + "iopub.status.busy": "2024-09-13T15:55:17.679658Z", + "iopub.status.idle": "2024-09-13T15:55:40.915698Z", + "shell.execute_reply": "2024-09-13T15:55:40.914547Z" + } + }, + "outputs": [], + "source": [ + "generator = TDUpperConfidenceBoundGenerator(\n", + " vocs=vocs,\n", + " beta=0.01,\n", + " added_time=0.1,\n", + " forgetting_time=10.0,\n", + ")\n", + "generator.n_monte_carlo_samples = N_MC_SAMPLES\n", + "generator.numerical_optimizer.n_restarts = NUM_RESTARTS\n", + "generator.max_travel_distances = [0.1]\n", + "\n", + "start_time = time.time()\n", + "X = Xopt(evaluator=evaluator, generator=generator, vocs=vocs)\n", + "X.random_evaluate(2)\n", + "\n", + "for _ in trange(N_STEPS):\n", + " # note that in this example we can ignore warnings if computation\n", + " # time is greater than added time\n", + " with warnings.catch_warnings():\n", + " warnings.filterwarnings(\"ignore\", category=RuntimeWarning)\n", + " X.step()\n", + " time.sleep(0.1)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false + }, + "source": [ + "## Visualize GP model of objective function and plot trajectory" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "data = X.data\n", + "\n", + "xbounds = generator.vocs.bounds\n", + "tbounds = [data[\"time\"].min(), data[\"time\"].max()]\n", + "\n", + "model = X.generator.model\n", + "n = 100\n", + "t = torch.linspace(*tbounds, n, dtype=torch.double)\n", + "x = torch.linspace(*xbounds.flatten(), n, dtype=torch.double)\n", + "tt, xx = torch.meshgrid(t, x)\n", + "pts = torch.hstack([ele.reshape(-1, 1) for ele in (tt, xx)]).double()\n", + "\n", + "tt, xx = tt.numpy(), xx.numpy()\n", + "\n", + "# NOTE: the model inputs are such that t is the last dimension\n", + "gp_pts = torch.flip(pts, dims=[-1])\n", + "\n", + "gt_vals = g(gp_pts.T[0], gp_pts.T[1] - start_time)\n", + "\n", + "with torch.no_grad():\n", + " post = model.posterior(gp_pts)\n", + "\n", + " mean = post.mean\n", + " std = torch.sqrt(post.variance)\n", + "\n", + " fig, ax = plt.subplots()\n", + " ax.set_title(\"model mean\")\n", + " ax.set_xlabel(\"unix time\")\n", + " ax.set_ylabel(\"x\")\n", + " c = ax.pcolor(tt, xx, mean.reshape(n, n), rasterized=True)\n", + " ax.plot(data[\"time\"].to_numpy(), data[\"x\"].to_numpy(), \"oC1\", label=\"samples\")\n", + "\n", + " ax.plot(t, k(t - start_time), \"C3--\", label=\"ideal path\", zorder=10)\n", + " ax.legend()\n", + " fig.colorbar(c)\n", + "\n", + " fig2, ax2 = plt.subplots()\n", + " ax2.set_title(\"model uncertainty\")\n", + " ax2.set_xlabel(\"unix time\")\n", + " ax2.set_ylabel(\"x\")\n", + " c = ax2.pcolor(tt, xx, std.reshape(n, n))\n", + " fig2.colorbar(c)\n", + "\n", + " fig3, ax3 = plt.subplots()\n", + " ax3.set_title(\"ground truth value\")\n", + " ax3.set_xlabel(\"unix time\")\n", + " ax3.set_ylabel(\"x\")\n", + " c = ax3.pcolor(tt, xx, gt_vals.reshape(n, n))\n", + " fig3.colorbar(c)\n", + "\n", + " ax2.plot(data[\"time\"].to_numpy(), data[\"x\"].to_numpy(), \"oC1\")\n", + " ax3.plot(data[\"time\"].to_numpy(), data[\"x\"].to_numpy(), \"oC1\")" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false + }, + "source": [ + "## plot the acquisition function" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:55:41.794609Z", + "iopub.status.busy": "2024-09-13T15:55:41.794517Z", + "iopub.status.idle": "2024-09-13T15:55:42.112062Z", + "shell.execute_reply": "2024-09-13T15:55:42.111804Z" + } + }, + "outputs": [], + "source": [ + "# note that target time is only updated during the generate call\n", + "target_time = X.generator.target_prediction_time\n", + "print(target_time - start_time)\n", + "my_acq_func = X.generator.get_acquisition(model)\n", + "\n", + "with torch.no_grad():\n", + " acq_pts = x.unsqueeze(-1).unsqueeze(-1)\n", + " full_acq = my_acq_func.acq_func(gp_pts.unsqueeze(1))\n", + " fixed_acq = my_acq_func(acq_pts)\n", + "\n", + " fig, ax = plt.subplots()\n", + " c = ax.pcolor(tt, xx, full_acq.reshape(n, n))\n", + " ax.set_xlabel(\"unix time\")\n", + " ax.set_ylabel(\"x\")\n", + " ax.set_title(\"acquisition function\")\n", + " fig.colorbar(c)\n", + "\n", + " fi2, ax2 = plt.subplots()\n", + " ax2.plot(x.flatten(), fixed_acq.flatten())\n", + " ax2.set_xlabel(\"x\")\n", + " ax2.set_ylabel(\"acquisition function\")\n", + " ax2.set_title(\"acquisition function at last time step\")" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false + }, + "source": [ + "## Run Time Dependent BO with Model Caching\n", + "Instead of retraining the GP model hyperparameters at every step, we can instead hold\n", + "on to previously determined model parameters by setting\n", + "`use_catched_hyperparameters=True` in the model constructor. This reduces the time\n", + "needed to make decisions, leading to faster feedback when addressing time-critical\n", + "optimization tasks. However, this can come at the cost of model accuracy when the\n", + "target function changes behavior (change in lengthscale for example)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "generator = TDUpperConfidenceBoundGenerator(\n", + " vocs=vocs,\n", + " beta=0.01,\n", + " added_time=0.1,\n", + " forgetting_time=20.0,\n", + ")\n", + "generator.n_monte_carlo_samples = N_MC_SAMPLES\n", + "generator.numerical_optimizer.n_restarts = NUM_RESTARTS\n", + "generator.max_travel_distances = [0.1]\n", + "\n", + "start_time = time.time()\n", + "\n", + "X = Xopt(evaluator=evaluator, generator=generator, vocs=vocs)\n", + "X.random_evaluate(2)\n", + "\n", + "for i in trange(N_STEPS):\n", + " # note that in this example we can ignore warnings if computation time is greater\n", + " # than added time\n", + " if i == 50:\n", + " X.generator.gp_constructor.use_cached_hyperparameters = True\n", + "\n", + " with warnings.catch_warnings():\n", + " warnings.filterwarnings(\"ignore\", category=RuntimeWarning)\n", + " X.step()\n", + " time.sleep(0.1)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# plot total computation time\n", + "ax = X.generator.computation_time.sum(axis=1).plot()\n", + "ax.set_xlabel(\"Iteration\")\n", + "ax.set_ylabel(\"total BO computation time (s)\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "data = X.data\n", + "\n", + "xbounds = generator.vocs.bounds\n", + "tbounds = [data[\"time\"].min(), data[\"time\"].max()]\n", + "\n", + "model = X.generator.model\n", + "n = 100\n", + "t = torch.linspace(*tbounds, n, dtype=torch.double)\n", + "x = torch.linspace(*xbounds.flatten(), n, dtype=torch.double)\n", + "tt, xx = torch.meshgrid(t, x)\n", + "pts = torch.hstack([ele.reshape(-1, 1) for ele in (tt, xx)]).double()\n", + "\n", + "tt, xx = tt.numpy(), xx.numpy()\n", + "\n", + "# NOTE: the model inputs are such that t is the last dimension\n", + "gp_pts = torch.flip(pts, dims=[-1])\n", + "\n", + "gt_vals = g(gp_pts.T[0], gp_pts.T[1] - start_time)\n", + "\n", + "with torch.no_grad():\n", + " post = model.posterior(gp_pts)\n", + "\n", + " mean = post.mean\n", + " std = torch.sqrt(post.variance)\n", + "\n", + " fig, ax = plt.subplots()\n", + " ax.set_title(\"model mean\")\n", + " ax.set_xlabel(\"unix time\")\n", + " ax.set_ylabel(\"x\")\n", + " c = ax.pcolor(tt, xx, mean.reshape(n, n))\n", + " ax.plot(data[\"time\"].to_numpy(), data[\"x\"].to_numpy(), \"oC1\", label=\"samples\")\n", + "\n", + " ax.plot(t, k(t - start_time), \"C3--\", label=\"ideal path\", zorder=10)\n", + " ax.legend()\n", + " fig.colorbar(c)\n", + "\n", + " fig2, ax2 = plt.subplots()\n", + " ax2.set_title(\"model uncertainty\")\n", + " ax2.set_xlabel(\"unix time\")\n", + " ax2.set_ylabel(\"x\")\n", + " c = ax2.pcolor(tt, xx, std.reshape(n, n))\n", + " fig2.colorbar(c)\n", + "\n", + " fig3, ax3 = plt.subplots()\n", + " ax3.set_title(\"ground truth value\")\n", + " ax3.set_xlabel(\"unix time\")\n", + " ax3.set_ylabel(\"x\")\n", + " c = ax3.pcolor(tt, xx, gt_vals.reshape(n, n))\n", + " fig3.colorbar(c)\n", + "\n", + " ax2.plot(data[\"time\"].to_numpy(), data[\"x\"].to_numpy(), \"oC1\")\n", + " ax3.plot(data[\"time\"].to_numpy(), data[\"x\"].to_numpy(), \"oC1\")" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/single_objective_bayes_opt/turbo_tutorial.ipynb b/docs/examples/single_objective_bayes_opt/turbo_tutorial.ipynb new file mode 100644 index 0000000..ba9feb6 --- /dev/null +++ b/docs/examples/single_objective_bayes_opt/turbo_tutorial.ipynb @@ -0,0 +1,424 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "# TuRBO Bayesian Optimization\n", + "In this tutorial we demonstrate the use of Xopt to preform Trust Region Bayesian\n", + "Optimization (TuRBO) on a simple test problem. During optimization of high\n", + "dimensional input spaces off the shelf BO tends to over-emphasize exploration which\n", + "severely degrades optimization performance. TuRBO attempts to prevent this by\n", + "maintaining a surrogate model over a local (trust) region centered on the best\n", + "observation so far and restricting optimization inside that local region. The trust\n", + "region is expanded and contracted based on the number of `successful` (observations\n", + "that improve over the best observed point) or `unsuccessful` (no improvement)\n", + "observations in a row. See https://botorch.org/tutorials/turbo_1 for details." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Define the test problem\n", + "Here we define a simple optimization problem, where we attempt to minimize a\n", + "function in the domian [0,2*pi]. Note that the function used to evaluate the\n", + "objective function takes a dictionary as input and returns a dictionary as the output." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-08-07T01:59:27.474306300Z", + "start_time": "2024-08-07T01:59:25.101273800Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:03.477703Z", + "iopub.status.busy": "2024-09-13T15:56:03.477389Z", + "iopub.status.idle": "2024-09-13T15:56:05.180187Z", + "shell.execute_reply": "2024-09-13T15:56:05.179805Z" + } + }, + "outputs": [], + "source": [ + "from xopt.evaluator import Evaluator\n", + "from xopt.generators.bayesian import UpperConfidenceBoundGenerator\n", + "from xopt import Xopt\n", + "from xopt.vocs import VOCS\n", + "import math\n", + "import numpy as np\n", + "import pandas as pd\n", + "import torch\n", + "import matplotlib.pyplot as plt\n", + "\n", + "# define variables and function objectives\n", + "vocs = VOCS(\n", + " variables={\"x\": [0, 2 * math.pi]},\n", + " objectives={\"f\": \"MINIMIZE\"},\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-08-07T01:59:27.502331400Z", + "start_time": "2024-08-07T01:59:27.476306700Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:05.182105Z", + "iopub.status.busy": "2024-09-13T15:56:05.181910Z", + "iopub.status.idle": "2024-09-13T15:56:05.183934Z", + "shell.execute_reply": "2024-09-13T15:56:05.183678Z" + } + }, + "outputs": [], + "source": [ + "# define a test function to optimize\n", + "def sin_function(input_dict):\n", + " x = input_dict[\"x\"]\n", + " return {\"f\": -10 * np.exp(-((x - np.pi) ** 2) / 0.01) + 0.5 * np.sin(5 * x)}" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Create Xopt objects\n", + "Create the evaluator to evaluate our test function and create a generator that uses\n", + "the Upper Confidence Bound acquisition function to perform Bayesian Optimization." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-08-07T01:59:28.802460800Z", + "start_time": "2024-08-07T01:59:27.502331400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:05.185338Z", + "iopub.status.busy": "2024-09-13T15:56:05.185241Z", + "iopub.status.idle": "2024-09-13T15:56:05.189688Z", + "shell.execute_reply": "2024-09-13T15:56:05.189466Z" + } + }, + "outputs": [], + "source": [ + "evaluator = Evaluator(function=sin_function)\n", + "generator = UpperConfidenceBoundGenerator(vocs=vocs, turbo_controller=\"optimize\")\n", + "X = Xopt(evaluator=evaluator, generator=generator, vocs=vocs)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-08-07T01:59:28.814460100Z", + "start_time": "2024-08-07T01:59:28.803460700Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:05.191014Z", + "iopub.status.busy": "2024-09-13T15:56:05.190910Z", + "iopub.status.idle": "2024-09-13T15:56:05.196944Z", + "shell.execute_reply": "2024-09-13T15:56:05.196575Z" + } + }, + "outputs": [], + "source": [ + "X" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Generate and evaluate initial points\n", + "To begin optimization, we must generate some random initial data points. The first call\n", + "to `X.step()` will generate and evaluate a number of randomly points specified by the\n", + " generator. Note that if we add data to xopt before calling `X.step()` by assigning\n", + " the data to `X.data`, calls to `X.step()` will ignore the random generation and\n", + " proceed to generating points via Bayesian optimization." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-08-07T01:59:28.883458900Z", + "start_time": "2024-08-07T01:59:28.816461400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:05.219975Z", + "iopub.status.busy": "2024-09-13T15:56:05.219805Z", + "iopub.status.idle": "2024-09-13T15:56:05.227477Z", + "shell.execute_reply": "2024-09-13T15:56:05.227127Z" + } + }, + "outputs": [], + "source": [ + "X.evaluate_data(pd.DataFrame({\"x\": [3.0, 1.75, 2.0]}))\n", + "\n", + "# inspect the gathered data\n", + "X.data" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-08-07T01:59:29.053969300Z", + "start_time": "2024-08-07T01:59:28.844461500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:05.229360Z", + "iopub.status.busy": "2024-09-13T15:56:05.229229Z", + "iopub.status.idle": "2024-09-13T15:56:05.437052Z", + "shell.execute_reply": "2024-09-13T15:56:05.436790Z" + } + }, + "outputs": [], + "source": [ + "# determine trust region from gathered data\n", + "X.generator.train_model()\n", + "X.generator.turbo_controller.update_state(X.generator)\n", + "X.generator.turbo_controller.get_trust_region(X.generator)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Define plotting utility" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-08-07T01:59:29.069971400Z", + "start_time": "2024-08-07T01:59:29.059970500Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:05.438704Z", + "iopub.status.busy": "2024-09-13T15:56:05.438549Z", + "iopub.status.idle": "2024-09-13T15:56:05.442827Z", + "shell.execute_reply": "2024-09-13T15:56:05.442581Z" + } + }, + "outputs": [], + "source": [ + "def plot_turbo(X):\n", + " # get the Gaussian process model from the generator\n", + " model = X.generator.train_model()\n", + "\n", + " # get trust region\n", + " trust_region = X.generator.turbo_controller.get_trust_region(generator).squeeze()\n", + " scale_factor = X.generator.turbo_controller.length\n", + " region_width = trust_region[1] - trust_region[0]\n", + " best_value = X.generator.turbo_controller.best_value\n", + "\n", + " # get number of successes and failures\n", + " n_successes = X.generator.turbo_controller.success_counter\n", + " n_failures = X.generator.turbo_controller.failure_counter\n", + "\n", + " # get acquisition function from generator\n", + " acq = X.generator.get_acquisition(model)\n", + "\n", + " # calculate model posterior and acquisition function at each test point\n", + " # NOTE: need to add a dimension to the input tensor for evaluating the\n", + " # posterior and another for the acquisition function, see\n", + " # https://botorch.org/docs/batching for details\n", + " # NOTE: we use the `torch.no_grad()` environment to speed up computation by\n", + " # skipping calculations for backpropagation\n", + " with torch.no_grad():\n", + " posterior = model.posterior(test_x.unsqueeze(1))\n", + " acq_val = acq(test_x.reshape(-1, 1, 1))\n", + "\n", + " # get mean function and confidence regions\n", + " mean = posterior.mean\n", + " L, u = posterior.mvn.confidence_region()\n", + "\n", + " # plot model and acquisition function\n", + " fig, ax = plt.subplots(2, 1, sharex=\"all\")\n", + "\n", + " # add title for successes and failures\n", + " ax[0].set_title(\n", + " f\"n_successes: {n_successes}, n_failures: {n_failures}, \"\n", + " f\"scale_factor: {scale_factor}, region_width: {region_width:.2}, \"\n", + " f\"best_value: {best_value:.4}\"\n", + " )\n", + "\n", + " # plot model posterior\n", + " ax[0].plot(test_x, mean, label=\"Posterior mean\")\n", + " ax[0].fill_between(test_x, L, u, alpha=0.25, label=\"Confidence region\")\n", + "\n", + " # add data to model plot\n", + " ax[0].plot(X.data[\"x\"], X.data[\"f\"], \"C1o\", label=\"Training data\")\n", + "\n", + " # plot true function\n", + " true_f = sin_function({\"x\": test_x})[\"f\"]\n", + " ax[0].plot(test_x, true_f, \"--\", label=\"Ground truth\")\n", + "\n", + " # plot acquisition function\n", + " ax[1].plot(test_x, acq_val.flatten())\n", + "\n", + " ax[0].set_ylabel(\"f\")\n", + " ax[0].set_ylim(-12, 10)\n", + " ax[1].set_ylabel(r\"$\\alpha(x)$\")\n", + " ax[1].set_xlabel(\"x\")\n", + "\n", + " # plot trust region\n", + " for a in ax:\n", + " a.axvline(trust_region[0], c=\"r\", label=\"Trust region boundary\")\n", + " a.axvline(trust_region[1], c=\"r\")\n", + "\n", + " # add legend\n", + " ax[0].legend(fontsize=\"x-small\")\n", + "\n", + " fig.tight_layout()\n", + "\n", + " return fig, ax" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Do bayesian optimization steps\n", + "Notice that when the number of successive successes or failures reaches 2 the trust\n", + "region expands or contracts and counters are reset to zero. Counters are also reset\n", + "to zero during alternate successes/failures. Finally, the model is most accurate\n", + "inside the trust region, which supports our goal of local optimization." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-08-07T01:59:40.084279200Z", + "start_time": "2024-08-07T01:59:29.069971400Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:05.444248Z", + "iopub.status.busy": "2024-09-13T15:56:05.444168Z", + "iopub.status.idle": "2024-09-13T15:56:09.703297Z", + "shell.execute_reply": "2024-09-13T15:56:09.703018Z" + } + }, + "outputs": [], + "source": [ + "# test points for plotting\n", + "test_x = torch.linspace(*X.vocs.bounds.flatten(), 500).double()\n", + "\n", + "for i in range(15):\n", + " # plot trust region analysis\n", + " fig, ax = plot_turbo(X)\n", + "\n", + " # take optimization state\n", + " X.step()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-08-07T01:59:40.126280300Z", + "start_time": "2024-08-07T01:59:40.084279200Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:09.704882Z", + "iopub.status.busy": "2024-09-13T15:56:09.704770Z", + "iopub.status.idle": "2024-09-13T15:56:09.706953Z", + "shell.execute_reply": "2024-09-13T15:56:09.706701Z" + } + }, + "outputs": [], + "source": [ + "# access the collected data\n", + "X.generator.turbo_controller" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "ExecuteTime": { + "end_time": "2024-08-07T01:59:40.140291900Z", + "start_time": "2024-08-07T01:59:40.100281300Z" + }, + "execution": { + "iopub.execute_input": "2024-09-13T15:56:09.708312Z", + "iopub.status.busy": "2024-09-13T15:56:09.708214Z", + "iopub.status.idle": "2024-09-13T15:56:09.712062Z", + "shell.execute_reply": "2024-09-13T15:56:09.711826Z" + } + }, + "outputs": [], + "source": [ + "X.data" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/examples/single_objective_bayes_opt/upper_confidence_bound.ipynb b/docs/examples/single_objective_bayes_opt/upper_confidence_bound.ipynb new file mode 100644 index 0000000..3855cde --- /dev/null +++ b/docs/examples/single_objective_bayes_opt/upper_confidence_bound.ipynb @@ -0,0 +1,194 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Upper Confidence Bound BO\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:56:17.411738Z", + "iopub.status.busy": "2024-09-13T15:56:17.411199Z", + "iopub.status.idle": "2024-09-13T15:56:18.380269Z", + "shell.execute_reply": "2024-09-13T15:56:18.379962Z" + } + }, + "outputs": [], + "source": [ + "from xopt import Xopt\n", + "\n", + "# Ignore all warnings\n", + "import warnings\n", + "\n", + "warnings.filterwarnings(\"ignore\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The `Xopt` object can be instantiated from a JSON or YAML file, or a dict, with the proper structure.\n", + "\n", + "Here we will make one" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:56:18.382048Z", + "iopub.status.busy": "2024-09-13T15:56:18.381940Z", + "iopub.status.idle": "2024-09-13T15:56:18.383540Z", + "shell.execute_reply": "2024-09-13T15:56:18.383336Z" + } + }, + "outputs": [], + "source": [ + "# Make a proper input file.\n", + "YAML = \"\"\"\n", + "generator:\n", + " name: upper_confidence_bound\n", + " beta: 0.1\n", + "\n", + "evaluator:\n", + " function: xopt.resources.test_functions.sinusoid_1d.evaluate_sinusoid\n", + "\n", + "vocs:\n", + " variables:\n", + " x1: [0, 6.28]\n", + " objectives:\n", + " y1: 'MINIMIZE'\n", + "\"\"\"" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:56:18.384797Z", + "iopub.status.busy": "2024-09-13T15:56:18.384722Z", + "iopub.status.idle": "2024-09-13T15:56:18.965528Z", + "shell.execute_reply": "2024-09-13T15:56:18.965274Z" + } + }, + "outputs": [], + "source": [ + "X = Xopt.from_yaml(YAML)\n", + "X" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Run Optimization" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:56:18.987017Z", + "iopub.status.busy": "2024-09-13T15:56:18.986820Z", + "iopub.status.idle": "2024-09-13T15:56:19.494115Z", + "shell.execute_reply": "2024-09-13T15:56:19.493854Z" + } + }, + "outputs": [], + "source": [ + "X.random_evaluate(3)\n", + "for i in range(5):\n", + " print(i)\n", + " X.step()" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## View output data" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:56:19.495618Z", + "iopub.status.busy": "2024-09-13T15:56:19.495487Z", + "iopub.status.idle": "2024-09-13T15:56:19.500405Z", + "shell.execute_reply": "2024-09-13T15:56:19.500188Z" + }, + "jupyter": { + "outputs_hidden": false + } + }, + "outputs": [], + "source": [ + "X.data" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": false, + "jupyter": { + "outputs_hidden": false + } + }, + "source": [ + "## Visualize model" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "execution": { + "iopub.execute_input": "2024-09-13T15:56:19.501788Z", + "iopub.status.busy": "2024-09-13T15:56:19.501679Z", + "iopub.status.idle": "2024-09-13T15:56:19.941144Z", + "shell.execute_reply": "2024-09-13T15:56:19.940870Z" + } + }, + "outputs": [], + "source": [ + "fig, ax = X.generator.visualize_model(n_grid=100)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..03bfd67 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,188 @@ +

    + + + + +Xopt +=============== + +Flexible optimization of arbitrary problems in Python. + +The goal of this package is to provide advanced algorithmic support for arbitrary +optimization problems (simulations/control systems) with minimal required coding. Users +can easily connect +arbitrary evaluation functions to advanced algorithms with minimal coding with +support for multi-threaded or MPI-enabled execution. + +Currenty **Xopt** provides: + +- Optimization algorithms: + - Genetic algorithms + - `cnsga` Continuous NSGA-II with constraints + - Bayesian optimization (BO) algorithms: + - `upper_confidence_bound` BO using Upper Confidence Bound acquisition function + (w/ or w/o constraints, serial or parallel) + - `expected_improvement` BO using Expected Improvement acquisition function + (w/ or w/o constraints, serial or parallel) + - `mobo` Multi-objective BO (w/ or w/o constraints, serial or parallel) + - `bayesian_exploration` Autonomous function characterization using Bayesian + Exploration + - `mggpo` Parallelized hybrid Multi-Generation Multi-Objective Bayesian + optimization + - `multi_fidelity` Multi-fidelity single or multi objective optimization + - `BAX` Bayesian algorithm execution using virtual measurements + - BO customization: + - Trust region BO + - Heteroskedastic noise specification + - Multiple acquisition function optimization stratigies + - `extremum_seeking` Extremum seeking time-dependent optimization + - `rcds` Robust Conjugate Direction Search (RCDS) + - `neldermead` Nelder-Mead Simplex +- Sampling algorithms: + - `random` Uniform random sampling +- Convenient YAML/JSON based input format +- Driver programs: + - `xopt.mpi.run` Parallel MPI execution using this input format + + **Xopt** does **not** provide: +- your custom simulation via an `evaluate` function. + +Rather, **Xopt** asks you to define this function. + +Getting Started +=============== +[Xopt Overview PDF](assets/xopt_overview.pdf) gives an overview of Xopt's design and +usage. + + +[Xopt Built-In Generators](algorithms.md) provides a list of available algorithms +implemented in the Xopt ```Generator``` framework. + +[Simple Bayesian Optimization Example](examples/single_objective_bayes_opt/bo_tutorial.ipynb) +shows +Xopt usage for a simple optimization problem. + +[Xopt IPAC23 paper](https://accelconf.web.cern.ch/ipac2023/pdf/THPL164.pdf) summarizes the usage of Xopt in particle accelerator physics problems. + + +Configuring an Xopt run +=============== +Xopt runs can be specified via a YAML file or dictonary input. This requires `generator`, `evaluator`, and `vocs` to be specified, along with optional general options such as `max_evaluations`. An example to run a multi-objective optimiation of a user-defined function `my_function` is: +```yaml +generator: + name: cnsga + population_size: 64 + population_file: test.csv + output_path: . + +evaluator: + function: my_function + function_kwargs: + my_arguments: 42 + +vocs: + variables: + x1: [0, 3.14159] + x2: [0, 3.14159] + objectives: + y1: MINIMIZE + y2: MINIMIZE + constraints: + c1: [GREATER_THAN, 0] + c2: [LESS_THAN, 0.5] + constants: {a: dummy_constant} + +max_evaluations: 6400 +``` + +Xopt can also be used through a simple Python interface. +```python +import math + +from xopt.vocs import VOCS +from xopt.evaluator import Evaluator +from xopt.generators.bayesian import UpperConfidenceBoundGenerator +from xopt import Xopt + +# define variables and function objectives +vocs = VOCS( + variables={"x": [0, 2 * math.pi]}, + objectives={"f": "MINIMIZE"}, +) + +# define the function to optimize +def sin_function(input_dict): + return {"f": math.sin(input_dict["x"])} + +# create Xopt evaluator, generator, and Xopt objects +evaluator = Evaluator(function=sin_function) +generator = UpperConfidenceBoundGenerator(vocs=vocs) +X = Xopt(evaluator=evaluator, generator=generator, vocs=vocs) + +# call X.random_evaluate() to generate + evaluate 3 initial points +X.random_evaluate(3) + +# run optimization for 10 steps +for i in range(10): + X.step() + +# view collected data +print(X.data) +``` + +Defining an evaluation function +=============== +Xopt can interface with arbitrary evaluate functions (defined in Python) with the +following form: +```python +def evaluate(inputs: dict) -> dict: + """ your code here """ +``` +Evaluate functions must accept a dictionary object that **at least** has the keys +specified in `variables, constants` and returns a dictionary +containing **at least** the +keys contained in `objectives, constraints`. Extra dictionary keys are tracked and +used in the evaluate function but are not modified by xopt. + +Using MPI +=============== +Example MPI run, with `xopt.yaml` as the only user-defined file: +```b +mpirun -n 64 python -m mpi4py.futures -m xopt.mpi.run xopt.yaml +``` + + +Citing Xopt +========== +If you use ```Xopt``` for your research, please consider adding the following +citation to your publications. +``` +R. Roussel., et al., "Xopt: A simplified framework for optimization of accelerator problems using advanced algorithms", +in Proc. IPAC'23, Venezia.doi:https://doi.org/10.18429/JACoW-14th International Particle Accelerator Conference-THPL164 +``` + +BibTex entry: +```bibtex +@inproceedings{Xopt, + title = {Xopt: A simplified framework for optimization of accelerator problems using advanced algorithms}, + author = {R. Roussel and A. Edelen and A. Bartnik and C. Mayes}, + year = 2023, + month = {05}, + booktitle = {Proc. IPAC'23}, + publisher = {JACoW Publishing, Geneva, Switzerland}, + series = {IPAC'23 - 14th International Particle Accelerator Conference}, + number = 14, + pages = {4796--4799}, + doi = {doi:10.18429/jacow-ipac2023-thpl164}, + isbn = {978-3-95450-231-8}, + issn = {2673-5490}, + url = {https://indico.jacow.org/event/41/contributions/2556}, + paper = {THPL164}, + venue = {Venezia}, + language = {english} +} +``` + +Particular versions of Xopt can be cited from [Zenodo](https://zenodo.org/record/7983779) diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..7c96fcd --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,58 @@ +Installing Xopt +=============== + +Installing `xopt` from the `conda-forge` channel can be achieved by adding `conda-forge` to your channels with: + +```shell +conda config --add channels conda-forge +``` + +Once the `conda-forge` channel has been enabled, `xopt` can be installed with: + +```shell +conda install xopt +``` + +It is possible to list all of the versions of `xopt` available on your platform with: + +```shell +conda search xopt --channel conda-forge +``` + + + +Developers +========== + + +Clone this repository: +```shell +git clone https://github.com/xopt-org/xopt.git +``` + +Create an environment `xopt-dev` with all the dependencies: +```shell +conda env create -f environment.yml +``` + + +Install as editable: +```shell +conda activate xopt-dev +pip install --no-dependencies -e . +``` + + + +## Cori (NERSC) setup + +``` +conda install -c conda-forge xopt +``` +Follow instructions to build mpi4py: +https://docs.nersc.gov/programming/high-level-environments/python/ +Note that there is a bug in Jupyterhub terminals. Type: +``` +module swap PrgEnv-gnu PrgEnv-gnu +``` +to get the C compiler activated. diff --git a/docs/overrides/main.html b/docs/overrides/main.html new file mode 100644 index 0000000..b68d6a3 --- /dev/null +++ b/docs/overrides/main.html @@ -0,0 +1,11 @@ +{% extends "base.html" %} + +{% block content %} +{% if page.nb_url %} + + Download Notebook + +{% endif %} + +{{ super() }} +{% endblock content %} diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 0000000..8404aeb --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,31 @@ +/* +Hide In and Out prefix +https://oceanumeric.github.io/blog/2022/jupyter-style/ +*/ +.jp-CodeCell > .jp-Cell-inputWrapper { + direction: rtl; + width:113%; +} + +.jp-InputArea-prompt { + visibility: hidden; +} + +.jp-OutputArea-prompt { + visibility: hidden; /* disable this to tune the position */ + background-color:red; + position:absolute; + right: 0; + +} + +.jp-CodeCell > .jp-Cell-outputWrapper { + margin-top: -10px; + padding-top:0; + display: table-cell; + text-align: left; +} +.jp-Cell-outputWrapper > .jp-Cell-outputCollapser { + /* background-color:red; */ + margin-top: -17px; +} diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..c51df73 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,151 @@ +site_name: Xopt +repo_url: https://github.com/xopt-org/Xopt-docs +repo_name: xopt-org/Xopt-docs + +nav: + - Home: index.md + - Installation: installation.md + - Algorithms: algorithms.md + - Examples: + - Basics: + - examples/basic/xopt_basic.ipynb + - examples/basic/xopt_parallel.ipynb + - examples/basic/xopt_vocs.ipynb + - examples/basic/xopt_evaluator.ipynb + - examples/basic/xopt_generator.ipynb + - Bayesian: + - Gaussian Process Model Creation: + - Basic example: examples/gp_model_creation/model_creation.ipynb + - Bayesian Exploration: + - Bayesian Exploration: examples/bayes_exp/bayesian_exploration.ipynb + - Bayesian Exploration from yaml: examples/bayes_exp/bayesian_exploration_from_yaml.ipynb + - Single Objective Bayesian Optimization: + - Bayesian optimization tutorial: examples/single_objective_bayes_opt/bo_tutorial.ipynb + - Constrained optimization: examples/single_objective_bayes_opt/constrained_bo_tutorial.ipynb + - Log-transformed optimization: examples/single_objective_bayes_opt/log_transformed_tutorial.ipynb + - Upper confidence bound: examples/single_objective_bayes_opt/upper_confidence_bound.ipynb + - Custom GP models: examples/single_objective_bayes_opt/custom_model.ipynb + - Trust region: examples/single_objective_bayes_opt/turbo_tutorial.ipynb + - Interpolated optimization: examples/single_objective_bayes_opt/interpolate_tutorial.ipynb + - Multi-Fidelity: examples/single_objective_bayes_opt/multi_fidelity_simple.ipynb + - Time dependent upper confidence bound: examples/single_objective_bayes_opt/time_dependent_bo.ipynb + - Bayesian Algorithm Execution: examples/single_objective_bayes_opt/bax_tutorial.ipynb + - Bayesian Optimization with fixed features: examples/single_objective_bayes_opt/fixed_features.ipynb + - Custom objectives: examples/single_objective_bayes_opt/custom_objective.ipynb + - Heteroskedastic modeling: examples/single_objective_bayes_opt/heteroskedastic_noise_tutorial.ipynb + + - Multi-Objective Bayesian Optimization: + - Expected hypervolume improvement: examples/multi_objective_bayes_opt/mobo.ipynb + - Multi-fidelity expected hypervolume improvement: examples/multi_objective_bayes_opt/multi_fidelity_mobo.ipynb + - Multi-generation gaussian process optimization: examples/multi_objective_bayes_opt/mggpo.ipynb + - Evolutionary: + - CNSGA: examples/cnsga/cnsga_tnk.ipynb + - SciPy: + - Nelder-Mead: examples/scipy/neldermead.ipynb + - Latin Hypercube: examples/scipy/latin_hypercube.ipynb + - Other: + - Extremum seeking: examples/es/extremum_seeking.ipynb + - RCDS: examples/rcds/rcds.ipynb + - API: + - Xopt: api/xopt.md + - Vocs: api/vocs.md + - Evaluator: api/evaluator.md + - Generators: + - Base generator class: api/generators.md + - Bayesian generators: api/generators/bayesian.md + - Genetic generators: api/generators/genetic.md + - SciPy generators: api/generators/scipy.md + +theme: + icon: + repo: fontawesome/brands/github + name: material + + custom_dir: docs/overrides + features: + - navigation.top + - navigation.tabs + - navigation.indexes + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: black + toggle: + icon: material/toggle-switch-off-outline + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: black + toggle: + icon: material/toggle-switch + name: Switch to light mode + +markdown_extensions: + - pymdownx.highlight + - pymdownx.superfences + - toc: + permalink: true + - pymdownx.arithmatex: + generic: true + +extra_javascript: + # The following are for mathjax rendering of LaTeX formulas: + - javascripts/mathjax.js + - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js + +extra: + generator: false + social: + - icon: fontawesome/brands/github + link: https://github.com/xopt-org/xopt + name: Xopt + +extra_css: + - stylesheets/extra.css + +plugins: + - search + + - mkdocs-jupyter: + include_source: True + execute: True + + - mkdocstrings: + default_handler: python + handlers: + python: + paths: [Xopt/xopt] + options: + filters: + - "!^_" # exclude all members starting with _ + - "^__init__$" # but always include __init__ modules and methods + docstring_style: numpy + docstring_options: + ignore_init_summary: false + heading_level: 3 + show_root_heading: true + show_root_toc_entry: true + show_root_full_path: true + show_root_members_full_path: false + show_object_full_path: true + show_category_heading: true + show_if_no_docstring: false + show_signature: true + signature_crossrefs: true + show_signature_annotations: false + separate_signature: true + line_length: 100 + merge_init_into_class: true + show_source: true + show_bases: true + show_submodules: false + group_by_category: true + unwrap_annotated: true + import: + - https://docs.python.org/3/objects.inv + - https://docs.h5py.org/en/stable/objects.inv + - https://slaclab.github.io/lume-base/objects.inv + - https://lark-parser.readthedocs.io/en/latest/objects.inv + rendering: + show_source: true + show_root_heading: true From cfb7f1d50b077f6b105f08e965be2fc5149d011f Mon Sep 17 00:00:00 2001 From: "Sara A. Miskovich" Date: Mon, 31 Mar 2025 10:53:38 -0700 Subject: [PATCH 2/4] add deployment workflow --- .github/workflows/gh-pages.yml | 68 ++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 .github/workflows/gh-pages.yml diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml new file mode 100644 index 0000000..dfddada --- /dev/null +++ b/.github/workflows/gh-pages.yml @@ -0,0 +1,68 @@ +name: Documentation + +on: + push: + workflow_dispatch: + pull_request: + repository_dispatch: + types: [ release ] + +permissions: + id-token: write + contents: write + pull-requests: write + actions: read + +jobs: + build: + runs-on: ubuntu-latest + name: "Build docs" + env: + # `uv pip ...` requires venv by default. This skips that requirement. + UV_SYSTEM_PYTHON: 1 + steps: + - uses: actions/checkout@v4 + - name: Install uv + uses: astral-sh/setup-uv@v5 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.12" + - name: Install dependencies + run: | + git clone https://github.com/xopt-org/xopt.git + cd xopt + uv pip install ".[doc]" + - name: Build Docs + shell: bash -l {0} + run: mkdocs build + - name: Extract examples + shell: bash -l {0} + run: | + zip -r xopt-examples.zip docs/examples/ + mv xopt-examples.zip ./site/assets/ + - name: Upload docs artifact + uses: actions/upload-pages-artifact@v3 + with: + path: ./site + deploy: + if: ${{ github.repository_owner == 'xopt-org' && (github.ref == 'refs/heads/main') }} + needs: build + name: "Deploy docs" + + # Grant GITHUB_TOKEN the permissions required to make a Pages deployment + permissions: + pages: write # to deploy to Pages + id-token: write # to verify the deployment originates from an appropriate source + + # Deploy to the github-pages environment # TODO: set environment and url +# environment: +# name: github-pages +# url: ${{ steps.deployment.outputs.page_url }} + + # Specify runner + deployment step + runs-on: ubuntu-latest + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 From 54217bfbbd4f33435e01e83cd042d8ce81c9d9b3 Mon Sep 17 00:00:00 2001 From: "Sara A. Miskovich" Date: Mon, 31 Mar 2025 11:03:54 -0700 Subject: [PATCH 3/4] Update docs/examples/gp_model_creation/model_creation.ipynb Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/examples/gp_model_creation/model_creation.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/examples/gp_model_creation/model_creation.ipynb b/docs/examples/gp_model_creation/model_creation.ipynb index 8925636..6a67f6c 100644 --- a/docs/examples/gp_model_creation/model_creation.ipynb +++ b/docs/examples/gp_model_creation/model_creation.ipynb @@ -11,7 +11,7 @@ "source": [ "## Building GP Models from Scratch\n", "Sometimes it is useful to build GP models outside the context of BO for data\n", - "visualization and senativity measurements, ie. learned hyperparameters. Here we\n", + "visualization and sensitivity measurements, ie. learned hyperparameters. Here we\n", "demonstrate how to build models from data outside of generators.\n", "\n", "For this we use the 3D rosenbrock function test function." From db49019af6bca78a562bf29fb055d9a11f840c9b Mon Sep 17 00:00:00 2001 From: "Sara A. Miskovich" Date: Mon, 31 Mar 2025 11:04:05 -0700 Subject: [PATCH 4/4] Update docs/examples/ga/nsga2.ipynb Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/examples/ga/nsga2.ipynb | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/examples/ga/nsga2.ipynb b/docs/examples/ga/nsga2.ipynb index 9f64d63..7cffbd6 100644 --- a/docs/examples/ga/nsga2.ipynb +++ b/docs/examples/ga/nsga2.ipynb @@ -151,9 +151,9 @@ "metadata": {}, "outputs": [], "source": [ - "# All evaluations are stored in the following Dataframe. Speific to this generator, a `xopt_parent_generation` and\n", - "# `xopt_candidate_idx` columns which indicate from which generation the indvidual's parents belong to as well as providing a\n", - "# unique index for indviduals.\n", + "# All evaluations are stored in the following Dataframe. Specific to this generator, a `xopt_parent_generation` and\n", + "# `xopt_candidate_idx` columns which indicate from which generation the individual's parents belong to as well as providing a\n", + "# unique index for individuals.\n", "#\n", "# NOTE: The data DataFrame is not stored when serializing the generator. It must be saved on its own for later use.\n", "generator.data.head()"