From a271a00d6e59aabf9d9ab0b29ba38a8db17b1473 Mon Sep 17 00:00:00 2001 From: Gopala Krishna Date: Sun, 27 Jul 2025 09:21:56 -0400 Subject: [PATCH] feat: Integrate community documentation content and clean up API doc links: fixes #89 --- README.md | 5 - docs/community/additional-resources.md | 28 +++ .../action_plot.png | Bin 0 -> 110984 bytes .../cum_reward_plot.png | Bin 0 -> 36271 bytes .../reward_plot.png | Bin 0 -> 40273 bytes docs/community/base-reward-function.md | 33 ++++ docs/community/best-practices.md | 42 +++++ docs/community/building-simulation.md | 36 ++++ docs/community/configuration.md | 124 +++++++++++++ docs/community/ddpg.md | 24 +++ docs/community/electricity-energy-cost.md | 35 ++++ docs/community/environment.md | 139 ++++++++++++++ docs/community/glossary.md | 24 +++ docs/community/hvac-systems.md | 57 ++++++ docs/community/learning-algorithms.md | 14 ++ docs/community/mcts.md | 37 ++++ docs/community/metrics-interpretation.md | 36 ++++ docs/community/natural-gas-energy-cost.md | 33 ++++ docs/community/occupancy-models.md | 33 ++++ docs/community/regret-reward-function.md | 41 ++++ .../reinforcement-learning-module.md | 25 +++ .../reinforcement-learning-module/agents.md | 130 +++++++++++++ .../observers.md | 81 ++++++++ .../reinforcement-learning-module/policies.md | 52 ++++++ .../replay_buffer.md | 108 +++++++++++ .../reinforcement-learning-module/scripts.md | 175 ++++++++++++++++++ .../visualization.md | 76 ++++++++ docs/community/reward-functions.md | 12 ++ docs/community/sac.md | 16 ++ docs/community/setpoint-reward-function.md | 40 ++++ docs/community/simulation-components.md | 22 +++ docs/community/system-architecture.md | 67 +++++++ docs/community/td3.md | 72 +++++++ docs/community/tutorials.md | 16 ++ docs/community/weather-controllers.md | 28 +++ mkdocs.yml | 103 +++++++---- smart_control/dataset/dataset.py | 6 +- smart_control/dataset/partition.py | 42 ++--- 38 files changed, 1748 insertions(+), 64 deletions(-) create mode 100644 docs/community/additional-resources.md create mode 100644 docs/community/assets/visualization-module-images/action_plot.png create mode 100644 docs/community/assets/visualization-module-images/cum_reward_plot.png create mode 100644 docs/community/assets/visualization-module-images/reward_plot.png create mode 100644 docs/community/base-reward-function.md create mode 100644 docs/community/best-practices.md create mode 100644 docs/community/building-simulation.md create mode 100644 docs/community/configuration.md create mode 100644 docs/community/ddpg.md create mode 100644 docs/community/electricity-energy-cost.md create mode 100644 docs/community/environment.md create mode 100644 docs/community/glossary.md create mode 100644 docs/community/hvac-systems.md create mode 100644 docs/community/learning-algorithms.md create mode 100644 docs/community/mcts.md create mode 100644 docs/community/metrics-interpretation.md create mode 100644 docs/community/natural-gas-energy-cost.md create mode 100644 docs/community/occupancy-models.md create mode 100644 docs/community/regret-reward-function.md create mode 100644 docs/community/reinforcement-learning-module.md create mode 100644 docs/community/reinforcement-learning-module/agents.md create mode 100644 docs/community/reinforcement-learning-module/observers.md create mode 100644 docs/community/reinforcement-learning-module/policies.md create mode 100644 docs/community/reinforcement-learning-module/replay_buffer.md create mode 100644 docs/community/reinforcement-learning-module/scripts.md create mode 100644 docs/community/reinforcement-learning-module/visualization.md create mode 100644 docs/community/reward-functions.md create mode 100644 docs/community/sac.md create mode 100644 docs/community/setpoint-reward-function.md create mode 100644 docs/community/simulation-components.md create mode 100644 docs/community/system-architecture.md create mode 100644 docs/community/td3.md create mode 100644 docs/community/tutorials.md create mode 100644 docs/community/weather-controllers.md diff --git a/README.md b/README.md index 2649542a..92834ec9 100644 --- a/README.md +++ b/README.md @@ -25,11 +25,6 @@ from cloud storage. View the official [Documentation Site](https://google.github.io/sbsim/) for a complete auto-generated API reference. -There is also a legacy unofficial -[Community-run Documentation Site](https://gitwyd.github.io/sbsim_documentation/) -containing more information about the project and the codebase. We plan to merge -all this content into the official documentation site soon. - ## Getting Started A great place to start is by reviewing the diff --git a/docs/community/additional-resources.md b/docs/community/additional-resources.md new file mode 100644 index 00000000..57d5c292 --- /dev/null +++ b/docs/community/additional-resources.md @@ -0,0 +1,28 @@ +--- +layout: "default" +title: "Additional Resources" +nav_order: 11 +parent: "Smart Control Project Documentation" +--- + +# Additional Resources + +- **Gin Configuration Guide**: + + - Learn more about Gin configurations at [Gin Config Documentation](https://github.com/google/gin-config). + +- **TF-Agents Documentation**: + + - Explore TF-Agents for reinforcement learning environments and agents at [TF-Agents](https://www.tensorflow.org/agents). + +- **Energy Cost Modeling**: + + - Research energy cost and carbon emission modeling for deeper understanding. + +- **Reinforcement Learning Concepts**: + + - Review reinforcement learning fundamentals to effectively develop and test agents. + +--- + +[Back to Home](../index.md) diff --git a/docs/community/assets/visualization-module-images/action_plot.png b/docs/community/assets/visualization-module-images/action_plot.png new file mode 100644 index 0000000000000000000000000000000000000000..9ce4ef0e64a6b866cfa8c53dbc63e90fbe92a53c GIT binary patch literal 110984 zcmc$`by!tf+cm!E?vySigbheHNC`*?(hY)iNOyOcfYKr$(jeWrRa&KcgM!lC@Xf8~ zJn!?pzw7t+cU}8<*xSuobIp0ragQ2LusWBL72qFH>X>p+Jy|g4{#j%#AFc^oKtV;q5+W z14mue&6SmvOsyQM$|S_Zcy`V@M5Qr|xyONtlb|E*bdvk$5>AeQ^U5`JJt zIXQps^g1{sWcH3gvw+0r&_LGfeLn^U@5fuS=ktD#w`aElhE5rxZ44>V<%s`%DNrbW z#FG8bTViw^&u}K}e_l^9*hX;v^Y$+0Q(5+Z|B4CwhAe8QQ%5#|5UFUF>? z42N6^P)EnD@vEt-cJSfP2OZDFGUyKtWQvgqJRV9s;v-GA3%ml46}uz<=LxVSw%g8O z)X}?V+i=E^#3SPTFRM8r$@@bRMB-V5XqfmN)+th$8H2Yzw{5py2lL@a^d?YYwWj1N zry!6wQ&m-EyP@-Lsx3&Oyy-XB!R8E=Q5j`aR8+&|(aZxqJ<83z#s>xllj{p{J1La0 zU9{L7fU7UUz8X~mI5zZh0FYzpm50+=| z-n~PQz$ECB*lvlqsg`=LdbpzfiYCp}`-bgMW*n_c14;}beOF0ETl|bmGeJe`kJobtetG}^GLC4?6pFH>;&ID?W2KRT^+YC zZ#8fCEp|p!J^D<#^5e(SWRkfcj+D>%4z zRq&<%ZlJb~&hB>|%_Zc$cb2*%=8sc(jI|y-2vg4xww!PAJ6U<5>DJFve^1C0+N1ah zQHiy$W(V*Eoq3iT*Arq!$OXDgRokQsJJXam{-mK3dxC!B#tjl$ePv~==g*(}OSajK zveYj)Iymes#V}fpzE$Ml=H93ZlKc}0*ghP+$WVSta5w2Vp5pcnB7xUxu_J6`{jg!} zZGzj$j%B^G)YziSWF^YCB28s~fAQxpUhq3j@=0Fobi2%a9~)cJZ$G0rJKDs{(ui?i z?pta-o?qurO--fbHmpXsx3|BisR`$)pA83}q%2DZUx*@y`N-DxZqc_TFfVWra9jI< zDGXBa$f&BDaq%EC_L=u%H%RSOW(;DJwyiaCzc_J!sIPxMThW2V7#RADRT%-s*_SEi zvD1mg=sR0pT}|44HdgU8Cx@s^F9Af7C76;*18(2rIUo1U+6hz$)^=jWKj`0|$^%JG z7lLYB(J4JG*O7kj-kn5at6U)l%T3yk1%KR-W%2DiN7m*?y` zfu#7|i{R-z$W|e(hYuqk=LAuXjg9#(Cy7ANZM{;cn~#HsXS1pzhQS}3CJA$Ja1dcF z;j`6qak~F3H5D_WGc*C#ggsO5>JyN)BPQj4z!7}4pTo+^iUy{3+iUh}@z?$^AO2R; zI;_;N29s4eInt~G{*qJ2ZEb`Z>Y#OP31gOzmM!{b`E%ek!-7o6P#jn~Y{riVssP0l z6355&1O){fr26>qtE;PL83L{^k1Yjhb~6?(FmJuU;cdUTV>|dJN*dXSb|Xy4@u;P8%c-g1ZMB`d zKqd|+T~TKcZM!UCj@~ED5sl$w28ha~f9@R`GrpR1TgSBIX z7NcohI=&XDJwcyv2@elX!)DzKU*L(`Lp?o2ev0(n$B)@zEjxEF zwtU*VZ&$R0gUw0Js+0(l*!9-QIRoCss?2rRs9n!y{Q_aM<<3UUFyePfMc-?I$GLhX zD3Hwg)UX?vk&C1Hc124|=HI`6S6X&szI^q{FOeHf7F=D}Wj6MPfUPfg2^0!&a2dpE zcba){9EeHc2~!{XEdY_FX00?KC*6#*b*8QULO+MHZYxcTI8R5a@wSqa-Maq=PowUJ zfdI#gDgDZRhEJmHwfZQ#w<|=D=_3PKK5!*V2_bu7)r!UqGmYX(%CpzD5AFk#;Zo{V+f0-rX zntj4h#oh1i?OhFWkri*_3h6HYl81jcfe5-_aH?0Z^ia0c%yQ#aPDrXvZ#(guoS>CH_|5M)$V2loI;H;`eGuFWv@aHjJ-f=IgKbTuahKo10IYiqkr*`zfV zG)mAB27(Z1K*Zmc^hZPg*4MvqY+$jA=yf?<5U?G9Ab`%8Q0~Nf-l$!rO+RJ*!4q@p zBqeCaK0fXF^YFSl;riW;sT!;z%^XTb<5~xbk48L{FcWNOvOPpbBTGCAg!!tSlN0%B zYkodj&Ew&|I_DYxK+NriWx{qi11|W)yPqpv(4G{6;dLIi5;IWEuUh;;#HS3Z?nt)A z($^D5c6ld`R@~Dr1wJIUN(Xl5^tvM@uUTUKygy$1)nUah04b}Zjj4vS-zDyYLKCui zi{trfYHIwRYg)TLD9onD@1jDhf&vUANig-9i$Wl*c6aT+6)r8O$n<@F!R`)5liSwD z;Oy*7E#>d21>cQq->&KiMM0Ylrs`>8>Z>*4$@cqsV-^6!+Dtv~EzRu2e%^LEk%hn- z;}5|;==@yRUanw1MV9q}s~WGOg98_|2zDSeQnF;` z=vXq-6;Ur3Q2gsExUirA1;WL}m6V3H40mRdfly?Y`a@h}8)PdctY_++0YwsMJNtbb z$udgx%DO-bs04(CPc88vp@Csqd_1=9}{bVlqffG0X8V6 zZOx5gnQO`HkgHRM;Si9jeJ^(55!3bGeKV-W3pCEN1GYLT^i9H$lxiVxp8z?RNTi$m zXiqjIb!?JS!FcBp_CqcTLI%mT!%1*Cc8yFoW5F-O!*GB(mHvkgNEUJe5)0s((T}tJ zlxCIEj{!R(T!yC{H*9YuNOZ#L(BtcmzfGLe4TzBdM)vhD^L?A5PUldKLL-MN=xQx~Q&%tzo$Ap-Kbg>awL|sd64T`=gj534}wWwR} z$#q{6?dbgc)-6?yOwlFpmd*$)v_e|k!}{(lGM|GOmqE_TXptu4yTZaFw@=#|OvPJQZSXK{Krzm@nu(BU5V;?A zm*LA`AHv(OFI`h+*l*rkLUN!&^$aZ|qu;v?Aj?KiIraTWGv7KoLG&iLuV(omK>Q=a z0v{8tya9n*Uj>;+v{?K!P3~Dn&P5N)!w3zKFg_tk?Le7#z(l#}WTOW=to1;cGONsJ`xWJ)S3whtwhlW3xrx?`5FuePr(>Suc4<^h{RKu)tk~6JMu_w1JZb-@xmSs*{xh~5kTf-0|Ek4me1b!h>@lsvnok~7CMqB$5NYz zT-H*nc-a8LZzV{x`1J)quw($Zole5b1!-n?f$Blts^UBt5yxKXJR@x4J!Jy|h6xag z9Uz*>F3*pt&NUXiXPl8UR0)QN#6cjMPS)~MDud3wTMoXeS@G;4w+0e20L4{MQNdA4 zri;^*K1DApE0an-2h7Fl?BEx*fGxgD>!BV#gCuorZ7mQLSX^9OZh*m?ExbT(1bs8V zn}CHRtXH%%#1Jv|$z1IcU7Ss{dpp|vbj_$m#ved3@T~&)DiyZ@1d<1l^a=FhmU@?t zrc~77`o!|v1X!1I{aiE&t5R-L6OH3|Y3K1mNXo&1XCk8vgK7cku;f0zk+E^!m;=A# zIQPoR%E4qiK(qEtNk38~aC=Rd#sJQKw?KR8o2HB+&|~H8S7&DC0ZUO-R=x2Q25o_2 zeaZ9*K-w|!@)E&Q7~vVNZ8$OAVYQAENAF99K7a1)r7}-M?oE)t5~z5+1I+TY7R&1A zyTFXcKgd_I{Pne9ZK8sa>-Oy`zkOS*)q})@HY*yTURuIb(K$PQk&_ z0U*^^vTJ602AG0pXa*`lSVAHL{N+YEzxC{NA&#K1aJ9&sCt1duH(vn4Rv~|GMpA9( zaf4JF%^c~$`M~`_Cl?o3iC)Q6@a0(*h&!?KQDw%{!>hovUqu@yyUT`PBuCo|IhP=W zdyKd#>zyy0YlLkFsJ%gYXmt_r_<3KLojs=3s0?rlCwqI&fc-&{nxL}-OOP`pe0MC4 zMA}aY9ECG_Ct6N_W^4dGYgnNDYy3%BK!#B2;kJ}_*7_D?0eBxjl4|AUg;^E}nJ$nPv(F=@@ z!guc~O-)T1>Zj^m83PW-^lJ~)SDws+mUZXvm!QM&+W ztxJkuK#qv(JYZ!LrG{iXf6#d;!qSk6iV|tO#IoGHd6Qbuju^R27eF$n9Jzs{j?C-0 zW4UDix;Vs<_)K9)6#M6OClp=$-=6`rK_BG)FXM*fzdfG+W!1cYD;4V7yX2M&FdN{A z1@*1zZsxzY1b?!H+8Ba_3p9&--c#Y9>ZnrpAL{Dn<>oR?cOysj_thoq=O=b{yv_Sd zS|v9o?&V8zX!cz}VWErm$`_?U!*UctEBaR=Q4<@af?N9f=pg6+FR z|GYgBfG=^_+8~b{g8ly*aIvxbfaJ4CNl8t2Kc)C@XD(-BvI-4=7jTgb zJ1Tg%xqE=9fS74S#q=aY3y^pGA$ z!$x(#q{Dk;W<+W#PjUL{ni}^pU40Y?X^nmTsy!R9-D*LtBxte!5`h$%NW%k|6W!4S z-GKk{*00`(?gSe;s-(OL7c&9{m;=4Qk(pngbZz=|OY&?jA21+|9aq`NSii9O(a|uZ z#WSXFe&~1(pdC@&59>xkGstPnNIF*$a_I;lP6Q#0q>Ot%`gbR-Q!KaVTd74{=#X-w zsj0~=3-jM+!NKmYUi&!7a>c9Vvo}_vZ+)_}L@n$@?b5QV)B-F-m-7=a6>i{pEIY$7 zCIP%4H8>E=sEgVI=f~SA?AgAkfN;JqFF*24)Reg-2Ygusthh9tbRc#8La;~c8es^tjl|XH0l6rJ`6YqN{k-qH|`J1 z5JA-ZR_JZlR{ts)QLHV77_O zx}iaf#YNd&Nc+RI+1nD_CO9X>B<>X3KNrM%zOqAii{E~wHJlJQ7*?IxQUSAd4*>ZU zc%0lo@b981ymdqL;A~9Ss*(2s%Mzs9zAvwC_d0{5lrmNGIL0&68lG%9{n6ef1z3~> z@MLY4@a+%cap3;xF0S#fOJnV6on|w$f83+`ON^N0k4$ zebY&pc0S}f=;8-&h`X8qRw&^8B-<_fgu$o%=2k18o}K*6aNViNxg1yy23kj4T)ap2 z7L}q8n zOglX|>0gbqKqYdwM9;!tf&8PV(X$sHdNm(sSPB~FJ>;`6?08h$ZT0wB#)sZhGyy(q zJIcLp2P5xE%Rk&H{F#oOX|X!-=uTcs3*G0>pGSUqTGHitA}s|wd;88TpZU0t9|h}I zk!Eq=$x=)MAhSEjE&N;!)(LF#D&Jiz@Th^8hZ7CgSLY}Ya=!wgv=F2LJoH&s7D1K< zRp=$^(c;;91ssFQBvj1f=OU2NJ;3V<1Jt(Jo~zYt8yN!N_GVuCz$f|g@*q5sZ$6+f;0rT z?x%+)(TX5VcBp|o7W{|+dST>kyd5Zi;GMdNa6+368*p%q5jQ=?D_Wj`ES5L))s`YLXpl4 z6bfeuzz+fbwN#su9Y&FMvHyU(=yjpBS#EuOeSSlO!NnzzHApk(j(`BaMF%8#Fe3lH zw6q7fYD7>2u#I<8LN3sNl92hc5rAoI031`K>9{^s@szO8$ItOH4jb@2JHO)cAV6Hbu2YaWm$^{PS-(-?}Y5 zX&9}MKo9X1n$y4-#<4bSB|aE8KP}YHZ)qf3#{0_8A#sBct7y@S=H^3O%$rH{lWrd= zl}n~aY^#^%b+NR@C!?BI@srlhWr-Em0s-8bHUP;bl=`P4QTlyw&8d=?bF zyo8W}w~9qT6Is!AhI>38z-tzKYJ;poxV9dqPFfK_NZ0D@%paMO-xn8m0syUYnQLO` zbN|cVp1hrN>VACAwfnW6eRO22)K$u0G=8&))@}J+SVN!*!|x>93$58$Mh%h0m~Tn% z1>Q()xt=|Bl5BG$k3VAz2y7GC$`nKQ#!5(Qmx|LDrdaNE)wHrmMM)Uiq&hf7x&;#a zyd#f?GJm;KC?W@ac=9Ib{OGW0p?RyRWa6dwAI5n%zq$aAC^(Q@>9ib4`e zeM>8zkaOn#H?g1>Ri4vKmE1dN70FiShImJ>Y8O*-=)*t%-ZCrI<>YH)qE|7ZsD3VZ z@9PIXrf;Dch4=^5UdL1g;hlSp-6J-&%Y)lPR)*@W*vf) zt%qpOYaLAPJijv*ZZo$;GkZOX^6|A3$EWYhshm*__FrV}bXB2_#Js7KN3J)o&UJ2l zFjm*%qE6h*iMCgqN*8CtTP64us!@hNa{{ByND*n5NO)1ZX(<6Xi-P1olsGol$-X6%1rxl%8lWrazgOq|>RU+rj5#o=?GS zZs10XnYcI=6}fFLSmwFwIjk3B3`f>*GIqx#-<6OU6sZ3GjaVYrtXcWY=C=)Zyz8lw!(Hii<(^gXC~XtVK5DAVhg*p6KQ%JwCYl{eL-k6SsHEI?J2+v#t9T zrrLMqh+m0lFmOl<*K*L-4^iVoCudqGlvs$k>#K)^Sa|mtGH*Pj{diA+TSW2Vv}!md zx20GhJ|8H$r|kbIfsUF5I%S<0j8l7YyN9@R@9ij}KE9mXAbh#o<>cA^uzvMt$`A(R zBxR^syB1t|g!AYDT#uf5EE=t;t#8LMx+7C zMlHz2O_xIiO&U+Le6AW2_Uy3rS;XfZ!8%siYnUURzgJpXEdPAD?>5DtDHOW#h{w~x z=A|+jH5sNYv^ZT>>uK~>k|vx9)$+fTmkNv9p}*9VCr{X@U;6;+Q{}U5Cb{>Cb+Xxq zSNe2?EK}4S6*ycr|2?$RpZ5sbr1Y?ApLh08wZH=-qj->Msqni)EgSH;G` zk4h6CAD=sF#|J9x7whKNPXe+nsgbO<;rE9U3qEQ-zy|}bPFKy~S*fYf1hm47NJ#_g zlze`Bk1m!OuR8#z*8+ldI)fDRuRvEo?W*R^HVUAF+~A6eE`&3oI=MNeLT?8j^~N-R z*%|9xoX#nm(jkOS9+}^io`V+*5Dgt|h)eS&kgeIMXSs=XEweBZVUrvL^K*=#Sn##W z%4=+)qlDU^s41^pV@wuXAO0SrmJSpJ!-+<6Ti5o>I^+5jWFFHu^`fBUHV6fY!g9GU zDP7c^1zLQeDJ=);Z@WEYnn*u!Y%IH7Q~L5iXBM=pG=P2-WYfWH@cE`elP9OJ>-Q`xlAM5JEEvXI1+e_X`L4Um=O%-eQFK@*29&lAU z**-{F_0abEr1mYZX)IFldJ%4+Nd` zaQCA-OJP_H9Rwn?q2Iqh%$ZT9iT~rpMB))_+CHrBYqvXD@&r4EZ#B=AKFA*{-Q;z$=I^C< zqnUXo%N{$q2+9bPwT@{V@w!|TNE-6$wtoD~#zH$IumA{ui2?=K{n7s0EJFrpLP@5V z_<1x50HinP#q;M+-@J)$5??5jE7QA;wDy6GG+`FN^R6ly@82QgU02Zqk`{cnoS81L zfE!6)M2iCH#8zVj`|SzOOlo89FbX1T{Kp|0toQ2u#=rGgpmN3NTD-wy3IDsu-P9iAHm zs5Y8S000A-57B~hL)u(GmM@-_-KXNAFy1Zqs|AaGoX7FaoL^X(v2S$np%lDPrpXwL z2F#cdSv~`H;rh`mvVj8h?;w!f7Rc5i_hlt+)28ps!9aFw9L)<I!NWr!_^`yBnP>3Q=n9Bhd@#{H^ggp;NVx#QMd`r<65#&(1MOC7 z+DwVeAy7Hd8K~{L0VyY6GR7hy(G0J;+KG|*18t3~*$GJ12HgA((1H^Vz(sg%*SJg% zStLRNeA~sI+T^D9_wV1KMTcb}8ugKLLM%_AKSm6L{A5Q;`FFtliqU<6RS%65vn8l@*2(sDuF%2n|>O$#x1<_^)2QIstu94?xEkDDkoK@@ifjcN58= zw=TGmWaxV#Q4JfdoWxT&S$<9V!!(3WIfj{uI%l^h6K)2_^OW;EkEpb>s5&&$On)!v z?S?9KTZQ$AG+Bro7t_z)|D}-E+Ybe5f=R5{cZ2^&yUh5k0uwI@=$Gl`I#31e3q!-2 zWiYOOgp)ii-ylM_iCWdktGG%%IQ^KZx_>j)?B4@{`47? z(zhfH!BS5zi5Mc@qpmpjC>m$UW&f zy1%QSm)o|ZcVbaP5p4rTbfLx{0fPDujf9U;!_3qXMyF@H(wt!l&E%uKbL}9+h%w!v zTwNUkf7c#0bSZ(jbIDrIvjvJ!P==cShto~HUtBl zb7B4HF1i#u6d~GiLrz2oeU7ypwpEo#Ew`PEE&j|`l+H8gg+v#fVv{jut>GW*JX?V; zPQcJNj6qhtA@nK2#iMdE@GV1z=J)0G=EvZs+r|K1CRGUJ<+8}l3iJCO7F z;hXe8F#G(-fX5|Un?qWk%!#1sIW2AflTrWL=jcsPf3@9OYzoZ*zI1PEZ9i}UP+mRf z;*IN(%^$S@6*OS>RnBaVG7v7I6lmk5+PLp5cE&Ph{J9m0?g}}xmq1*CW>7MWzgNnQ z|7GceFw4yC!IzzelkSBN0$o%MIjVTFiEUmA9BO92Zf6CTO-2I3q5$}%9CsvcW zx^I#BQ9TQwn@AP=&czv-ul3B0K>yW;iC;AF)=y^dBM={PrC!n;Y~lB-ceV$Mk?@%6 z&7O9ekx$g-*M5r^jG!^ra3kENBHAW%i;mRplr6Tf@Tp`QX=WD9#{0EYr4cQcG!DBx zmIvx|JO5VBi`FH2J{`3Cq*_f(-P#rF)GCz#vDsRgu8S4_GE3U^K&aS z@G+aS`n~&RuTW!mm5XRtEy$DN5e*y4{#mH(7M3IA5yx{^UWqcOU-D!9JZj=j2pc`(ek z_{U-YgddfCN zk3!m`w8yTdFC$T95iy@7*h<4|9s;|nw)6b7&-SKgN+q}1YIzQC?86E1+Aqw!L7IXF z5LXaD5P;tbp-R#}8kyu5x`V_4jfdVJk;q|%PU{V8Y-=x3%B6gx^BHA>CBhZ~IW*?o zw;0g|NUF!&J14K!WuUOb0qRe0B}u{b`~7uyuqE!|6%4$~Zq2|5GyBCFKIBX`FX*GM z&XBVwc|d-APmXgdyQ;@9zB&1t&fDlySq>96>fZ{qLTEH0Y%lBeyUpFqr-=EHp@Pb0 z?fC&5Pv$wXS+6x0R4GE%HST_Kb%d2-u11wjAkT7ndWv2^-7h-#N(Fp^mn~Rz%Z;bgdDAK54>v# zQm(f7+QhV%j~c$Q!KAfk6~kO^A}f|Cf9(mj9=mG)M9Je+#1J2TIdvKqeHB zMnE6<&^b^}9LjBzY7tu7bs=4)Dfs?b67_aEXlUXKAFAdK-u;>48=}m~aB`A6r8m^!t{{)xFIsnZyO(IViL~n=IaZLU7j9EhMVdY4hTvr-umDe2Q@)b!mtL`-<<|Z7j?p>d0J_>6)suU<|ZGH`^M{-o?{zbi%X$e*U zp~FZS^^x0><@W~6o-$;sa?%~%ew^DqP^&@eFe3H32j^n9n#A`B+q-`cWV{B>oW}Pj_L~w6Z=y2Ed8P-2=_>5e`m3$t15(q-eL_nV&H2QsZeR+% z5$8TxxKf2oXocy`Q=D-330jOH-m8Pgh7RUqO2^QezG)y(zpv(xIotiNY_Jjgn2{;f z6-DD&%OdTvgb&M6RP{i%M*OK~-|NWMhWSf3Xp-)IJ)nM-gA0ioIV%+P!j$@23L5a< zzr;1UQ_TxmxEkVxx^Qk;wuNbClKY(Ec{+zHjkGVT$rloRrlitN1To&GJ*%r4)j<7C z1=s{~#JkKRpthh(PDu$G{w=@0Q$Z@p31?s=<3wBfUjT=xzsDJn&aca-r~9kQh=*WE zR?l-z4vylYUPGZvewnf|W^>U>(ygXNdL6kBPG=`BMjKt)n+qCdSnNotVwgQu-P2?w zhJ{g~LW0jq@yX`__5xx_2m}vMu)z$R;UHQ_uuy}>KIkGFjTk`R%f?(Y6|f_awNNd6 z{Z;pKP!d50Wn@HqcMOqy@k0ctlY7m$faZhmg%k6nJOtMv1!DBxV%L&{efUP>J*!Z#MAuOCaTdZ(i)|e*!I<;_1vVV z2>~tjh64NB=J&BZrNdq7#CEnB)%e#>c{p5uC+@xPQqwKLNusBGPmUkGTF9hWgb7ib zvaF?ws<~rjk{oCx48l{9%a^ikB7eiW%AoS`FaxrLgRlmi4G5u5AoMS$;h-|?4ul&k zC+FwQT^{2)CU$l#aQ-A+$dU4DFRh*F_U-=l-~n5K0o$6B0ApiXsKcSQ%c0gk!0pou$ zIWOtplPxrhQ(|RTy{{KwFg)epg^QjsNI7;aLgz8-f}m9U$fZP?lQqA1C^kSTadj|d z33YVm(DlsJ-;YJSf7ku(VvG03*O{1~Z1Ol*&ucT?oPY5p%ov_*-Ok14ozfA2hkA8T<{_LDgSnxtiJCC9dJpYa^C`9UZ1Fl>9oLJEM@5j3;b3J zon-*o&GRIE0ig$JF{|}k&Ga22mQVd}sseIWS%VKna69shmz%CnNb`7G-1~qUCiGz~-BX*ReJ?mID~Dp1k<;-;`q$FZ3T^aQWf2k*l4K`F1PvhKK< zW`g=(T~g1!U0kih?<}slC*B?ay&$XcDYVhwm&Zdk(eN-0RcJ0w3vZyje!-(HZWiO}LOG|EjDbFAECA0d4Gt-Di=T25s1IIx1H#%r8S0Yq?P@w-bIC!|nl?*DK7su__$Ww7k`=X%pSP9t1@d*j7xBvj~ z%Ib<61rtg1VwI-clxJ3p zZyod`@S?Oa3Rolw$5jjV9UtUrDP6W=yvwr2Gw-UHc>l=Vr8RHjNjAn@5K6b$^{8yR zc}zsFTql!@#jWoSLSGMN14it$pw2w za?o9LRkDy?>3{0s@hM_-gif;!B;bI>uftlePmG*8WgsYfjz@^vra^yqYn;KrI&>>qu@jM}91^_*n>Mfwc zD(byK4Z5$Q!E^&FjT~|VeM`-+Kj9!_IDwMqx8=n+Xta{KSR(q)=ePUu6G>IyLhMK+<#uTsh@wh&B8yg!fj@kAe(0m>S4rej|IN7d}0UbjiU=ZM# znmjnGwYR^|@3UnhdAjm~L1z+Z7gG8>WseWA#9wB(m^1~bl+CQAts`?0KX;2pvd&Dd za82!M#>Z_uGSZfXl(?zMLT)&R%jOuQb4vegBoeQerO*r-iK+|vjs^T17D9A!XcqML zBF~6PO4oyOH$w`jNDMgsehZGRf!0vgA3GqKBPdgC6nCGJDuoe3Mndc(&0Sn0raH6T z-s$g|-|fIt`V|)qNXqwWd9(`u7}s3BOMw= zy@V1ucrbL{V`tvwIPqJ|g)cVd!A>?+3tYDgSWsnPhZitJEHKu{HC<{zs4$GM3mCXS5I?rgZ>7lqc!G19FcvE}yQhZ9|4176SF_-4J$ zQ_7nof@={JJk=>p+v5GT&uGn`!e9z0veoQiF3XN1%Y5PUHc9QhRDd4H#^sd!Inv`E z`F(~wi|Y}qs5!RAmTi14R?^chMm!SFvM>ALnoJMIfq+MR32}laJ{D0EDy^*CcN#wM z?(m3jHi%$|x#j-1DgQ4W3=^)plDtU01=t_;OljkI7Th|cmimsn@|*dZBDu#9=T=7Y z1PU}gxR*SzwZ}Em*j_@IrcIiMX-a{ogc^MJPj{!rUs)l?sx(r&BovF5SvKCpZRu1) zxq8ceNZ4_Y%E#Wn7H)~jf}rDniuqv9;jW?w)k|E=Re}Mx0GQ#r$qA{$cA2{!DSJ~x z48H^@bg}5g{`;^jH{_@sp0nDJQl$v3RjnY(AM$|4Ybxm2N?z3;3w5;n~vgmzy>>Hm; z>r3VHxAFI%tMiAG9Bje1M9OBPYGWLBeivGOPF~_#vtp7Ex3DT6q=6naDU6)6IijFb z+SK+3lBx@XE{V*Db3ip2>Q$cD%h`H~_Ddj&2aTRn%ca%pLty8#{iV+6Nz`%^iY(z< z_uYLc%$#ria``={J!{Q;LBrRQ5b#oYiMO2OK$3qbc7)$La7}GvRr8;KRiVDVg;2unBtr;?)i!X+hRm=Z0+D?3y z5d#V?tuCzNxyDX!Bbv24V}H8uhCaOsX}tjvuW%yI0Jf;YEa@n=__k4NYXga~=6FI% z{aymPHt{xz=hB6hLJr{TMZd-I#&EtCC#~- zv#*2O5P637V~)HhubiY?+wpKgP6oxFO{*{>is664x@IID9{jOsaMPU=!+$oTXZITZ zHX-1-9!`W()HtkULCO6|c6ZPZ9w;>IHD>)r=++vTj=+RkQB_x}dtW)k!eBN^pszpy zpEN|@7b))cM$^N-`Y;j8NNF=%EgxJQ_M4AzacIiDR9nMsQeb;k>D6%Kovp?v92q=Z4 zO=n+xRONrO;fg*7vknW697ew}AyYQ78Og9jZ<}G4OR32-j{aP5Wd$kL|2Z6pdiOwF zm+^|+=T!nnqtktc=f2j(<3l^|8sIi0{`krxhYqhe5EnvmFFY6zzWjtiCh-BT*f}2c z*#44*4USpG7hqZ9?q8TLAziE3MYqbg5&mo}YtFD|d;FJQdlXUfr!Zp_?j|OkV~ZAyqlq+}S25!TLF?47xt$f|fIAYS4XUK7c6KUz7{;hzq+;d0*4T=+coII!` z2e;v?)(U1^3}$?ExM|kar2=Ep4`ZSCp{vt`eXaTLaif=C6~Y+SIkzYR{R67sco|3T zM9MkU*pkhZ7VB0Cgj}&4+%3WehXmpX|5PAYI0*Hhz`p121&B1_vKNaB-PaQ^YA)q? zY7w&QN(v`Y+jHqmm)w0k$~QPn?$bDAsf))xA|NC!92xM)@SeLqCxSOTd!w2dIE2qW z^(;_igNjWow( ztpH=@@OgXh%?O4Pfwinh&K6Qz|FvH_zS9oAw-*Sr41IPwnvz?ua%;piI2q1$KwT>5 zbMtfW=q%%-48;7GqK0!aIUo0OpCh@H_8F1K=vhePE>8WQ(5dwJFoX?p45*U2mgdWS zSOF@QUM@w5>Uax%0|C>CV$ec2U8j*-9b#v|XflYj>gEZDeTLaYJ*6PdKcg%5m+qZg z!1k|C#1>P??gxGUGV(;|4dsH39JldVpJQ1OG>s9)L`2;sxopIx(rZRLE}KswOrSSs zDD4xFp#}YNN+w$AVa#H?tGu9P(&Df67=CLS)wBrlHttq2%bNQOf6n>-wA2#Qf zZ3fz{lDWr%uQz{kGR1tOWL+V31n3B1jItw5~cnMZ>>=EGw5)|r$YTkwUt|BHr``|eav zX7eSIEmX$eD?D=+Jk^M*lQ3D;VIcc`-~G4(lOD=85u}k|%udSuenR2mU#p!torVBfvfv%SX#0*hG;2v9+9gPw&b>6OvDAj(B> z*vaJBZ)&_~m{iEKcv`C4X;+;GdI4T{E;W5(iNT-(C&bB*!|zKaqwg4ry<3eTi?+`ewWRF>9IVb5J_ft~K;v zyGP)^@x|jYy?+K{j$-3sZH1!%8Uz}lv~K^RER|?NCtlMG_9LgvK#Qn(!6z#5d9(3` zd^HNR06gN@$mlluKS5YIMPJ?QJ|4%prTx06Hvm1$$34X|D*MC!!sod;9i}rfBi9vl z|D2UIf00iV#n;(C`aqSYblwyt8s+M!rb_CLVc{-nP=I^HOl>SvY)|-~LccvVkI5SZ*TEZxhDw& z;`WZou=c5}bdl+o9aTwm)8H>1&JtSVrk#9Afb-=M6%uQ2NRgs`G|8tlscyy>I!?YKdg6-_l4-|L3YKF0Og9f1?;B5t&aIS8oB0L=}TVC3&Zr$ zAj^Y-crQGFi$zE>oaqtz-$L=lUA|bg@h__--MYCMrG(Uid7CL-YVK)aZ}%0HS$C!% z=9XaG8^ki|Z-nz+pz*D1wzdf}n9S;+#^p9Yl>THXy*{IodmNoA60}j>W1dk9#Gvg@J&*$Uy9vc!Kb{mP@!AD195NwB*8VQJjJpH-jF(U<2j~HlaU(+V@$((($ zqgFPyz?HpM1$P&T|0`QQOU?u_V;NgOaj;vkd*k~$4?5V_MHKt*g(4>1!z`lMucatG zbmM3pma)PWp`SlwgwPGpQ2ucXZjBrfZb63Va94OuUJdGw)G2pCo&^76Qiv@?k9()` z(9`@^ZO1qy2*PCELrL;=V1i`9#e*{f!^@E21N^W*KMF_Et@|#+*UajwC_Hb!MUptu zy9Ru%Aht^=WS2D%_~w~$N5bv;h0SYVP@ctu_~{-Woy$>tS%bcF^hLB2RqV|6%E^LD zA^qQ%q6HRmB1JKCtNzL@k5MMLN~Ow=H@)vNBc3w^tE#~zx`iWN-$Ts%jSmGG)K{Uj zBQf#diu%8(%*dh5!!db*DTrAsL`m$9t9?$v8g}PnW>ZekU2aHsMTlsx%q_6{{g2z^ zv*a2VG`qxmf_Ibc@aONje*_iyH)t-`Wc4GWjEkNHGSz*?*Aml3Wj5ZW+x%0X^r&HQ zKwx-l37A;eHChaAlO4L;bZlw>hm)^HR6jbxM_Vo-kVTGnWCJL$21H>0cd-M&T#F95>**DzzCXnY~}JCx9_Qx5&J962ZvW#5#3-sM<= z^*2v|>P3v=A2a2AKXfNrm-g`krxGqD5f0MfzJR{<2t>PC6rT#%hhIJeSx{Uo z(B7d}it?$SUw?Smxss7G@CM)lB5Idg#sJpDi;I%u%yYoWasnVfe7-uMkUZ#{Cb6^k znuOo`WVN&2T>0o0K2@mTgR8*3SrH`mbDlc0xqC$9ZL1zBO3I7;0PFUt;C2w zokuAf+`;YszAL?u7K);Q60hs^Lza}UcZeVyHSU>kTaYql4vK~1_dTk294S-@L>I^R z4FF^TKp;eOD*Fe9*@c8C1BL`C2(;tKYB;bQ&(IWuqA%@h`Yctkc_Ycl&_o4Fe z9C6c2Su>HX>9 zH{~`MA~!kqXaq&{>~8P5;3`O6DA-O@R>>J}KcweX5AWSK_VMEw4oZI#xqw1J+U7A# zcq9@3TP@*oxCxxixO<3$P622DE^lNA9su1m4xA|%V4nCfrRS=#o45B5$Bb72+GB73 zHZp`u-XYRlRQw7N!x zNA>QMn^3>HwM`G15H|G3|Q(&DJ-hXApZBjcQOat`d8(vSK`+xNe)-x$G%oE`0@6H(~gk?uqI7C6n%NJbd&xL(+b<#cxMc$fd6v?j#ymFPryNzx7 z7F~ZJX*Hj|Tz63{Mi#fv zJ_kUMV${HqKlET&!=LtwU~{}__0miYFDU8CMWqMN8T8igO7o~GGsp8qAJ#6_U~ta zU~sL}}v`e984t5nJtGmW2%>3U>Sfg0I&EW*N8%9;2;Cd!6GNl23O^5;>d z=ho+c)DtVrnZyRSt@+H+J_=X+vIEQce{*gnj=9O^NIk>{QD|Y+4PS*1zzf_g9OMI( zNe(5r9^)#`Q3s-nv#KCh`vJVUyRfVjuVnoZt!8XfPN12_UHtr$@kc;S<9IP?nUv+k z4Ugw^Q}}i{=L+72f)UBeOP)=WHaj9A^6Xf*+&;NymP?K;SAU;=SIuCLT6Pl4>#G+_ z{$<#j-Chq;_$dEW^We8{;)VW6#8OjkD71nJJgP zaf~YZ-r-&UYwM%lgV%prQ~xrIxJU8!JfSdA0#mq1af{k^4$oD&Hf_On?)N-lFr%D< z%0Fyo*4sz}*1yg64>f7gb{1_XR;hCS`A_=ZoPlE5z*gFV&8)efnUQB6q4UH^$iKkr z<>Ml-4P@usg^}RUaHRn4l&*RvjC;F3zX${frMt300DBPq`MPs`OA9NYPlXgO2%n(!8)t_>BZHk3Uqv@g zyhOmOVS^2t{p~1Yd2BXAh0)~fWCpmOnB_G+MGpmv9sD75hi)!f2`VVFl}%MX4$@>V z2o_tNTpzsC;XH)gQ9Fk~C^=(zNW?^;!fqf{@=nk?$J44L`j?vt$F zrDMh~Amz{@raPRxD=MfqG;x-F@%v+CDgccxlG1f^u&>qCA8Q~jQAfQS{icMs z`>f%IUz~1RYka}=_R*LJNo^e=Ng;=VjrGyz=ilzWTwF|_L!H*2@X3Qt3{JKHX^bBn zuNhuD33%LR`5Esq;s2psPHX@~;J99>8=K_Ip-0;u!a9QJIY8(Bh0rtL$+C;1JERMG z2Z;b-G`E|vukYO$yybE0>a6l$wS$=-jaku2;F?|S>$kI9`n@~U-=UinVi`X!n)-Wg z#neJZ8x_VIY@lcIkzS-z!IB7qd}RCFGW}+&0~=&Xt46wdfR~i775AfK*uZM{ZB>$( z0UFjhqkTpQ)CljoJ@f@jMA= z4SW@7h9=>>d%%MFJXn`r0MkN0BHD1E4J9z4jsIMTLklTD|*4@W0KRix1_DcjiFSniaPG7bPGTHF!SfuztSfp z3z*U3cBbOfpi|e5yMN%P4L$OcOT4M=!$SxSTn}ubyG4==T-JO~3E0Fm&!1wxWQp6U z@Kr=EUHwEaLPR+v=vH`)R&FnT9r&bSyka&N;?*F?z#P!i#j9NrrK8A1-EOpnQu5VKZdG}vCi%OcJwM~m{Y%KLy#;3WS5EIR`KIjKITkh9QAf27is;gmCm|qBK5~5oA{SnLIE;K{0V`v zguzjK&7`dp!zE>7Y#lwcgv%M0i3m}FB+|Awefl2Jl}CT#YC=WdJ32BQ|GZxn{x| zOB&p`(U2jZSjrgikJba_%moGe1_;iwg3hg*e_xsn=%=BKrGdFA8$LLHlIDV=zJp?)3Wc=ke-PR@>FMxNDxD0<_r zsQZkbp}{vZkMxHJW9<88^jw(HUH5}auvoB0Hg6Kr}};|)Vv z8D1t2)HE%=PwiBpo3^c;>4!)i)ai_;e5L};d1^FmD-<1z>HlUYA&34QDvD$*Xt%lc zov1=RyN4UW{HdUNV0-==B*J54k9*W?0z{Xldw76^RK*&NFcbAHFD4)nwJw#HisI4IVh$*4Co0HOr-3Hb zd#mY&7n`IYstDk)fGTJ@cuophu|P(1N6i}Lt25_sCN7M=U;n*w1zf3S8}LL(#r6!<*Zx*!a~W|qk))6)m>q~ z+Bo|fEu*}|d(EVEIo1BM0hT2yDKR`2?kKz`t!5v*fq*6ockY(JT;wge&~Jt{SnAYa zI*2>oja{eS^GR%G8-!Ub&ZN-*09iq zl0MRO<`-GS-$dabGE3zm1b7fhZv~NsDtave+^u_BzFrl*BlMdVgmr~*M)?GLUD@LU}$kikDE_HT4=7k!7F zcO5SUrsDQ8X290K`oGc&af2CEA3{mqip;|XeY2s2Dri--s_h*AG}8^+llM@c?bpr> zsauSMuXNrexcAAuraeat{t&=c( z97Mn(?sLOZGu)Rnk*|bst7|u&Sm! zh(k(%ru%cbFxsoXJNkj!@1=o1LAPTx-U;I!8xKXrUTjBC!(Sey=TYDS-VipUIx){-=`ON4mN8;!2ge45i7kayzjQXA(Q(L;MT9lD;Do`n0bCY_%+3Xy?iG^xIARwb&16h}U@M_+ed3 zh5A*qRv_+6UGr%SSA7EEY6%q(q#BL_YE;clToPf{;o8u0zZ_6cf1D!-evTuQAHQCy zr9=|Xg90*ICN-TgKs5>j{aP<3s)K6Clv{Di(9we#3z7tM(V5LTGeQ^bK9e=-N6Qqy z(7$C$-i78D!>8*RQ|Y&JT;Y+h0b0wKg!Du`&;M2mD2<-;$m7jR3MM=>xUP6Iod`Abj+_zu=!*qq)lizor*){A7`B$aCw|s6 z>xfHl4Az6m=X#ZlBrXMVW`XlX)LjwGbAH`SB!6hve*NVb$j=CAO<2$g&5JN)4kZffa+kzQ6r1Cr>^FOuD z%eSR!c{m||#9OZ7V=dt@8t3Ivm41~o^7$w9n?8hgmSIPuBz9M0TMWSSFl~fr_P45U zZnT>F(%sgf+dw?uai`f z91pZuJ}6r5mdFP1Md5xmV8JYrC+2Nko^ct<0<4l8>sLf16rPHv+~11nWO~upqo{Er z24I0GSTl@DUnjq{ARr;gho)~#hu=)hgvQm}>{n4|4v=qXE8L6cqh@SvW;@)mUyQuI zcR?7DTzJ!T*P5>!8G`huE2INr(qvE(tr5VP&WSAktyeHwzkutJB;~aL&)j-Y5jcPFw^oDG|*-C zTd-kRF#p1Nao^rlpE;o&FO+b8aAZ^i?3kuSavjfn8F{6=;tMq!dLlk-e&aO zma-HEImbqcC%y}o zMkj>h*4SwKL%I(qdZ6QhXO&;-V&&wj^+oF|0~ApaOpES4E9X(Rik7J2JpW#K&A_J} zt4Rh9tAV?J`2z#at-9=2ccUd5>XL_y397vDtMBgNiTsdUccBNy91x!IT#@a!Tb=!_ z%&)(CVXO7n90NB=3h72t9HJ#!ua4EuaR4E3Zdoh){@qquTQsLHBRS+lqrbIwIGzuF zn7iq%L-*?d?6dNz7{D*CE}cYfan@x$4%fQiZBUlryO$smZhC?7n?!{C`^=v6jn&_T zP^BK+7ZpX`o0QS-v~AsIj#uIm(nMeTDp>CNZ6*Bq`Niyclk`hx!plQJ$DPFpry_z1 z`6L=;qm`(|rYhm=NY(gzz)=~M+$NN%z)F_tI2!a0SZu}+uit`~V~WdD7!70GL)(;< zl7P$=-w%(@Zt~Qf`GH`sP$qI|8di=cMnO4zS7Xt9WXiI@I+0>z86(Ygx%dz^D$Z!} zJe(=~Y*)%VB%H?iijE7n8-6VrvX+#<;1d9}Uyxb0FeA{wou}>1=I|V6Xua1%&Y!r) zuB4hh`wg-`fI9&0Me^&rqMeE>ZQc(45*UB>KNEWeT}2B5SHexF&ayXC2=VKn*jFnU z-YBl^?#B_(O6Z<8Vn^;qHqjQk$?8rCBQ}DTD3~#%_(79@qMF04TQprcvOMli`-CmX z_~DJ!{H_cWS4`^p2DN6ceQJj@7|-C)c4<9#3_4^ag?7MHgS`xX`(6$mMz>Fa+m@)k zCPUx!;i=o_Qr{pV06PJjdui5-oN8)QfnWx-2H_>xsE%TeK2vuNd#@l2_jUe)Js`C6 zu74P6Ck@}IqM)md6fR;AVC%ph7Q~g3tQ@Wa9N}16L}D}qn2;7OU8dy<+RK~n&gt?Wc=T6K1)D)88t)Bp=QVQeQ5D{|?svKJV?pCkz047~eiAqfmtJTlweg@p<3QJovI8mzD~2_;Qa#hT2_6B#gUjKN)j2%Yz@68BaYz(Uc`ZsAuW>?=&l$bBfxusR9DHOTD z2^57rW03aW()^fFR6FpSnTi;4`=E=zL&x#)gJ}C+ibFiJh$#KJkqUV{3kKDOg|vT9 zxbWCDD#v*n*bXE3(ZE5VQV?(Ga#H}_u5X(?f%%m4XfwRi&xH=G%oKNh<}xHnJO_}^ zC*7Z3L*LC*phx%o;rv&i;HCE(?Yf-&PJ8-f)tMgx3BTNC>7@9KEpJb3%PzPXBy<7~CHGxZG|85znPuM>$CE~wU=Bp4DAm^Wqh?g>a zM|wMIVN4+H2rdXipg@}L^|SOw@}>=WW09DmP`NvNO zw6${GrVz87)q%SUX9xn@OJ)d1R%Hhfoee29rqkQEf^y?OV8M3k#)ov#*T23tKYb%7 zru#z!^)Aa&rim8vXOFYYzBKt`5~86R>`nocCbG%rr@ObLhd3dYA*A^8>#mA9eIi=S zSQEpQ+n!7$b>EK;HsX_nXIs9-%b zZ=it3#6{dHoD;v!NYj_ znm!;3Pho!m`Ia~exHr)58(MBf%jye(>P2KZvl0A7O3e*cQK~W3Gu8Ff!d9wEOiB9r zLd*fIhOU($w+M@D&SZWHAcud;*NpFx|Lq3vf;`-Hjn+cz+_yCRDy|t2@!Lce0kWhA8{seQ}dh}Lq(3)IkG|4nJX=s$@~h5*PV>dVLjXdGVY8Ein+@GeG6 z{=dyI4bk>|>x>@V>t_bevW~LTeYsM6Fwh@} zSj!G5+HJPPXj#x5wmQxIo7Ti@N~>z-x}6zPePRQ<8JBgVU*$Xb{KiYNlAkA7He(SC zY{rEOa>%wIoR*Gg)A<;qechER`0;>Cy<(q#i3lTP|^5q>NioOL=JcQ22rbd$A4$eKisph z%8%FTd{k1mCnfZc?`Uy>vdW+lq$=3@PW?&)x&B=j34KDJsA&V5`R5;%O`z+v`29^F zep=y^lr0`yHHhno4ucXX@6E-pm#bH;eCIXzdc+O!{WwY5 z-NsN~cV-K23(#MhxRh(SAEaXpgau&|KAPi3E4K4!+~ugWB13+O-F-P1d#qQ$b#LyP zX)QG1Q^MQBWA#z(dgA%VO{>D(qqmK}(19inuTqPA0CAV_8@I+hFUt_nD8ASZ$50Rv z+zuFGaeGA$)W@Wz--WdKtH~#OtB-5Qqd#WiUJjb+B@}j^8|mMPy2;?*YZHtf14fxv zv|F!o^jhCYYS;g=icS8c68;*)rHwm(D48BuIQ)#_oT(ddCv78`#gZVBFc!f%n> z@7$w7Thlm+>GI}brvt6F%u8f{(Z<~*#Q7jNxj&Shl>(7y362@vmtle)_j9^kZ2~=x zzJC<+FIc~~B-A2CnX*1MNAo(~f8?I4>@tX;Q4-*Yn)jaFFmKNNkZz#qL=RROIlm5L ziC-vaK!kJm0KfuZ4T8ICE=%$Y{xado3~)0!FdFD_mRfjlRGg5Wp*rpP(4UJCBc!dA zj0LH66+0L=)e9LgYpZN1mlleZ@8JA{Ucs0a4LT~7AwsBH=hq*%wIOv|iS3a7rk6oW zZm&jfCMtiK5=tL7&gyueNxUceQ-coPb?W8d65zP4rDDS zNCKnB?>b!Xo_^=%5agzD7Qdnc>Bcb%jV2Q9Y;JK>Q9bF>g7bjVQ%gBYf)pNZHU}Jh z(WkOJPoEl#&73e|&DBax*i=P(o2W%irE{w*-PcQoH9OuS&)<)vCXxm(!yUg_|Kia~ zk7h>KPW8EgE^#ceGlb4ET@bdvw<0kfGOLo?2Xe^s!pG{MKZB^eKbJpU;>)RK-%ED5 zOg}CZ&)##=@GhFLRSoo^82@5lWT&7-w>m3mfLk_gEY(}*E9B2nvAbB%rVzw-I_Asu z5Od+uUk{ja1BPiTT4E!gXwNBZ{Mp3*Hl;_`lY$!bdT!W5yo4IpP(@@L-}o*g(2a}* ztb_jMnRkSnY8kyc-~669c4RAV%PmQbi7=}Ss)J@{B)5SaS>)#@m1cj!7Bqcf0UixZ zUa=BLBnhz4%Oxf|F$dH$%Sy(@j@0jLW+nc_+Qq+dM@4H}wl~l4|I-bu&K*>uH`rM- zERQ_*Y%)n|a{vj(DCd?Poe#e!+NFW41-wvFxn3vRj!h>g$1B8hr$rr=p35@bf>ht1 zhRpxDJ*-^OG?>)D8@LIoP&|mO$=9+G2ia;Gb8=#USP8C47FyG{B|QXS+G}8{2tXU- zrX>0Qo>_l33sQLuU^U z+(}!<-5T=*PB+2~PGOzQ`#&gIM)Gb{Y>z*(yBNNi3jLj(z$JrRB~Qii^1+a#Krrm= z1HeP#2=K5Xn4wAK)ER{@;1z5-=6Zs|_#-N?Tj4FR%cpqtwMtI`U8 ze*rjKg8YBsT>*RBxy&|goE+F%DDeCX|LxL8Ny=~fh*Erg98>>1YX|t;-!8yH8H=tJ zca`}pj54wanF~uVtOdC&U!cBe)W2OnUmb%{U;N?9%&Yo+J>n+*K_ce|PSkG^Gy@-v#8W$1bf{jk%A` z6o4^`^K1aL_A;2dM**fRw(k;2$EdnY%$ zqN2~2#5$&aTdMwaZ<@XB%|DK4Fm1I!mNddO@VdWL_5`zu{>%DeZ3Io9!2GO8cAl;* zY?yx(MGhIPbo}ebkrEwC9?|b_kbf!4yIrYav%LZ75V7PiOE~NT#XA!Gdnp*ET?XGJP_!& z!y1aL;(#!}xjb{czLENJ(nQ>v)XF)Qb)k!apl9qtf+Z`Os8m7i)oeM<8uznq_oL?> zzw% z^O76@9oi3kTbDBf1T?oJE-pd=b5A$a^Z$)mxb^{%``N${$-wl1sX7Om=pNc`EA6~xn)(& zLh09C{?&=rvZT(P;)4MVROmASx#=&ZImC#L!I+`vX-?{^ruh_zPvyjICsQ1rD_4TH z;Q92SRmact6sg@Du6g^B7>u0LHWGqVIyNhAVmw8#tZHG$Vw1Hhob~kuHNd{2K3R}TvSa1KEc>e2-lNx`jb7ZF6T+4lq+0>@%KYuHapVn;D**G70L5Eh2 zU6Fsch1HUpJm$N08ye@r{@N6UCO_O7m6%Ji1DpU?*OM95fkt(jtgg%7J||$hVKT56 zsaNEps4p)_f5Z}OErFgx#2Scv=kixi#j&4t9@ z@AAt_(ois^B>#eSsaV9PKc54f`Q@mqld&kkdTR;)iDb4hzQxn#M#*F-Mmi?EN&p69 z;t;xEq(G##_|W^U@4v5~%(i9%@K*g`+$!+i>3wwY0ccTzF{z&Y- zvM*6Ye>K?rgnt>ok9fqRD91^`bP}NYBa#V0iJld@6PkLUC+@ovG3)<#bA$#xBl_S_ zXnVhIB@884;nWlLEx%_fk`wi$2>>nxAxkH5W+$Jv#mFfrfbH^6LhA3;I2Cm#e!)U{ zCW_(TQ>&-Gwxz2?W1R-oN`8cIrWGweEVU=1 zv0nx4>i)_a9tjZ!EfjJuWtvi-B&I5#yaYwbu=EBU$MLl{EIA@wj%GZ-GUa#*V+ZiA6X+@U0ng9r{vRQ$AAL>XN;WfUlX-h@(Dj@@4P&=N#RufH01@@ zoGH7zo?x17$Tc*W0%Gko@(N525g(MaZ!$%}92~fb82esx zT)us&Mxx@d_r&i5**@$3t*&)(+iymuMQiqpB-b2V-d17?aEkvc(c8{SX@oulf!1PzUf%M5n5Rm0Ds{8Wi z0xm32-9|mdfz@Bv^1G9L?MBuO0Ut1&Y5$nUc5+&Lj9mJI@eOhrDh0E}$X0*RxWm-n zBW_;G4-T@j%Qaux&(MD}*_1b{(RqJ2_Esj<5$CPP0_R;U_O>IegH&H-14HMvd!PPU zFJ|*poQ_cY!A*C_!oX<^yx$&XhT+N{vTTMqQh4n0-i)|Ou)n}OwQ|EZD@V`3utBlH z&;xzkU`a4)sB>i1+}s=iVo)Fw@iN7RS^+p(B<9O{JsHlEue^_6AUgF3H;sDG(WKnC z(|b`@3j=^2ERPg%_qd*mn$DmNHxv7Gbu^QGkhLd8o*U0Gv{~DG*gyN}(Iz1I>fIRbO>ZfbZW6zw=|KbHU^P{0{_ z@rdt%azQVayiPthB;<)956cH_WriQ@momtHFxIuTi(@^NN;mikg@Q*QHA~!}UbQ#X za7gMJeVHJmtJ{n)5(R=Ol`>omW&Cuxc_i^JQ} z>tZPO``@EpUV!B!3@_cDbP=Cf57uZ?(1yg(JU@nJ_jnp;B;BP&w}b9{Ejf(@hK?Eh zkK%46qaFaUG_ zOzZ+9GL%LYYOAX$alw{j9AI6Hi2^rN28@DC{0IIvUc{YPFg1^-w*9~$-)~s)WTNhQ zEY6hMw%7SL=QCH8aEWj4M_tPTi64jcWdVed_7m>(Hos_p9vn1R{Q3GX4Fd7*@|E&e zy*(=)rBcqlIn10ma@T|oet*qpcTJC<8;YIyjc7)f3~4usI*+=frX#944xyVwN(@oz z0b$G~Tu|njexjc)M$0%q4cs7-2Q_qyMC?|4!%!}0ah!A}@BY$?tWAw5b;&Q@s9U|) zXr*j98Wpdqm>}0S*b{u3=VE1%f^eYytYRSh;yrWglCNrrR@zApEiQwoG1Cm}yc;qQ z+&36iIHG$jO5oWf__#dn>z)19q3Y$i{40|=+BI~79s~1WD;Ute46xk}x9AXG(lQ4}yzq>PeLr`uLonC)^OKg9?hofGB?`jr09zu3^&FompDYMJPv-{JH-Ll!K9w%YPk#8dgGR9GW-jOhM*ACj<^2?ef?ni!z_Y*OIo&znt=Q!bI_6PGb(GsA5?L%Bc^wX!vw|;L9m|V7~ zw-SnAG!AcDRcRy*pN6qZieRWol9QN%bWs#1xBQ)ruCSA;g5yP-<;S_#CZ?`4e9q$) zD&WcNAFLdC6_( zZ-gHi6^CC!{w!og%>VtI{HNe2h7Fqjl&aOy8i;QFDg4NM6H$UX=;DCuR!ir6fUS8< zVl*=MplpmBHyP@FY5TV(ezIinMc_jODN}0B{2*VKsOB~FaqcLdHNuta{T;>gl*vPQ zLU(8Z982wPEOF;|eaJ_vA`&QpdiF|BmodgI z%AiNRiu||J0|716yNTSlyDMfFIvZujGr6KKuZVcHQ4E%d0P9^TtCqjmYtTI}RigUR zds3ryR{qz}_I7ipos0XA=!Noi6GSlc#{A`LB}4eTp_~eB*DB{$VVR8C79Kz(_ejRN zjUz~$eDxJZD}nM{x1^07G9%xw7}QysA-jZa{@~j`1?v?Ty!WKWsox)vzD-^2M6T>g zKwgmol3rY=i|J5Mmuk+;>#w0#h7T@V$V) zWc63a1#%>+AW*MF=4$wC2r*zG~e==`9Do#>`ZT`0D!3Sy%isXRL1volR{bvlogb>=7_tj2GX+*q3+2Vyjza1_59VWTx zol+KydE&a#p|vCh?bA{zWip7#Pqeb;D`%^0(%?PtuF>~PUk)-9z%A|!AP~rsd4DR- zTVJc#!oi~bKHyDk({?me#Z>h${KV_v1sE8@!#dzs22c*gNM;{4@Ybjns2L%WE(ZqS zc~)q;k_O@YokI@aVmTkw!2|qSDm0u}YUJSgaqFH>?o;DX{a2(X!po zR2K&ki~!0h*6|EMAu&(XG0sBsP5;Z~Uof)Bem<1#&cY>G(eKsv2eofdYQL6svM7PE z=9Ma7!i0F|h9rT}Y!Xi}_3S~u{+-1_$LFN7Alkbtj;~tuf$EU2keG9s!t8#M&)qA8$*l?tezxb{AUpJ~l>}-9I zAn_VAs%Z6BrRWO{0(KLi<3Izb+Xoik zQ=5N!1I1#MB*wGOpKe_prSt?|&A>oZ_?Q1jE>Ob{ zbG}FuiFT6g-~`{E5BYW6P2~DMt0jbGsnra~Ek6sFq@yA}c!n-B>f}f3o}y0?y8>NG zG^AM5CU9~8*=9B1y!Y_S=YOzo=#6`qSJGq?!*jP$*Owi&DJ);#6xqsL@v*7>llJb@ z5aDa0#v4R3VTT9)+Ewu9rbII(LiT@}``MOUsaiSQkE_AYh)ND|ql06yyzh$;CT9rj zBYI|rvwY{sRgcI6yWxR$GI-6H!0?7N4kwm``N>OW~REc!Z4q^dT^Vv%5n}mL;cu ze)jbl9TeM)+eF;nr7jyLXhr4v2?}T2J@v?z0(PtDj|I=rT4>TTe2uVhAFXYd=G-n; zFv^8!%?1IJ=574N>D?tnuCW1q%`MO0A&&g|o_PMt6avcx-87rilu6textdH|GoAT@oK>n}K0dwE?_912J9EPZSJ;Nq3%Zu*09h!htaVkCj5Jb;vqidxrFE$&(&^Z-o)vX+{w1W{zwa zsIpdozTSJN-6j8uT&G>p*gR6=)vFWd+RZZ6fF9AshhPX8;C+8z}#8)sdTg)NPAC$H$TKL7(O(j#Je z`&Hf(j=2nJCWU}ZhfI#KL!kBJ{g*4=D5Mrj<(0Em88Mhlp(jPjZ$EHJhb{}XxzR(U zoZ-mwW!k-l|Br{m^)B^ANzJ|e8J;<2^MMZ^7{aVxu5m(LS%`bjo~G@B5ped+%J*lf zLD)17`nx%?)=_=x7Zf{GA0dE$2@aF724xynR;-l7oBgo;m43@+?*hhn9s$7vIrLmV zkA4Yh@JEa5xo=E4gVA55`#TIO6aPAmB9u!q+f@F*y8?M$e2ODiWk}c&#k{b%lQyJYB0bOjOM}JCKlJd)vp}JZVj*bGSo@( zo0MK{aIpzi*?AVx>m`LC$F#xEx^Uz}Ye*gvrXolLQL#ns4wUBPtiQ4>!0cA#QIh#(l_)L-ayz{}?#r8w2L*E@s)WJu(-=U=JN>F;oXv->kFmCO zI|}1uwyr$`Ea>zEx>Zj8`hgHOPAP1=5VkGspAQ7 zEggx@lSd-dP(8!9c5})4$Cu|jB#&XG_i>bx%kz{atcu*o@ zX983p#CaXy4X0KF6R8J`z!lCM;IT^Yl0#RVY6tf?iqd^s^Qg+3iB3Q?pBy6+!HY%X z0Ymsq+V{wZE&1woo?B6)cWRJQG(mX8QZeTnFLlU0zj5l1|7;jhO$HN=ov@hs50+xM zxw5deuXM6{kkYdxUTQ@9d-~h`LJ&qKiT>aYJlYhQekNpgtY5I zxXHl|%BOOHAoOq(WNqlvvY74{S7AS9D{XEv%aN>#c!+Epb*!)y$e{gN=r98wUD+(8 z#e7@XCm;>;$o!>XcJyt{nM3v;@b`j)b1etrw#Z2G|+6 zZpbp>R;&BOMxSj!q$Yo-wGt|lvlkA&7dWfPGkIOFHFCcYvX#E~O~S<&hYw#6>|Zo% ze@lFz)GwAfCM`SoXfwSN%z5*IWY8mO z_U~g7vg5}90;IOSZs`VwcaU&Eul{Qs%q_2;Zzo13U9*n&AKcSLySj_}_L z!{LIAKK4yCK&yOg8lg}u zlfO~;P3@p1YI={(w&~~aAmxjjA5~ZuG$zoi+{Zgk0b0}Z?dI*J!kRPvk?f3(4_h2v zU9ULDPMi-#m*)S3QCPe}kQ{?NnjELSQaewqU z1$Y4)?+{;w7{U%BIeH%(D^}jkz2ok2_Xgmysk6QNJJsLRto}1uuB}Wb^*+ zpT?2Z9LUeVxsVbJfYJZ%Y$mF97gRHgdM2JLk0c5$?NBSst2Y#jBiJJ^(Ki70tGs)! zGhHIKhimi-$)8>cYY_mUy%+}S^@5*i*eG?tR^*~vy78-mwhS>I@ex&gW}Q9dhw30h zXVZ_iU?7940-71M#|0bC9obi1>7Xqd0Ni+hWP`8@)~HnS6=m{>(1T@Y zQy300LwBpsw&x(DpY_$*;eYS$$|5KE&jL}Rn_p5`D!z5tGL7i`+bxXI=DaRD{eD-f zux}H}0AR*Td>jEZ5B_`E_nHqYbIF_-sb3_Bvpo1y$i+Hfp#pGIHrzK)0Ga7F%L@_yIF=8EV&1_)rCl=@63&2^EE;?|L8L=rC>juH;{4Q zC4L9$#xEsIMp>FYDka^z>Er%tz%XUS3Xow;fGHgU2)Vi!cm$tGnSXn$nDjka;NHq7 z4kEGpdyAhx4|fn-7>DBxybZlU$;}JbLLdh#y7oOJZ*b|;qQnN1nMpt&IzO+KCr5ji zqxxT+o+chpx*bKuGj_^jPlJ6eO2|{?@(74Ntei|=T8|%^Lb@ARP0o(q7C|5&j%t#z zqG#NS84PKjT^)}1`QNm{Y#1LQuwmijkrhE6_Pk_TtLQLRKhA==Pgw6)_clyPe@(dS zPG6TnH`#|DPk!OuhP*8+HB73|Fb9_bg*-cIL6?>4I3PIZ`b4c1-T=XK@)GPNSR#W*2C>oi;~i`KT=h@<>A`&pGT4EA2F2?z3-g%2=+{r& zT(kbR()ACRW-`avq~w240fDU*rmgc29@3qi4-@|^+n+rmI9REA=_;#Fk}ynW$O(zN zYh*xhgnJhs1^)4$aU2=Olc{vRRAA}JhKlT)C~63cVFK^Ft(X)QX`x(|Bqeb1t!hI+ z0IRbZwxJW;-h@s~v>nMexDo5dFv5hoS(@izKbZLg+XG+O(XNsD91RUOyakzJ6dm9B9 zjQ^ari7@D~_IKZ*>Bn0y`6C^%C?MMaeT|6ycayxIpY;C$3%J$sK)zROgQBu2hlwDq zlqX`Y3l2vo-+T~z_!2pClRq=PFKs0x{1T^U}Q9>wyu(C%70iyfEIRv5Ea~XCHb^Kx*YJ6H|HIj0$Ck) z77LIOio`D#VasD52arU{F{4|cNZD{Db%AI0cYMGJBwEm3bvBQRx8}G%fdC5VKkJJq z$B&I^*gY&GU8jOiOR4rLlLnPs%vb{z#JHtVuI(?_CV-Ae%5WYaaao)c&X^Vj*1}*U z3bF3{Ih*oNRb3ZJb_^n$2lm~VYF8maLYJ4 z2RY!}FCy-Ib}kwj`-C}=_Ugs6pPn|oL)tg0R6f@u{lHYB?3RRd=cE#zIm2zu{49LG z1l>cZ1(F=rKQ?M-ODs>@}lD&?D zOu(y`lpST~uab50$VGo~;+>v=e-u^7O?E%*_SChWOHSyX$mSzv?`U{L;!~voDL9ae zM*&eLMtR9;)+*BwnfJ{+jt-V@2ihCg)8+t!CYR_o4Ti2ET&)k^oT)|q#=Z{7b4=WK zB)VAn{%l9k$3ZvCm00AhtVYr6ZxjyY8XMG6S8n5U>IvczD*@&Lr?t-P48&BK*VnRl zg;Q}YMwp2hS2tN~rrj@dx==Y)WXXe9_w@KEjiox77Z*dRTzrjElrqWQ45c6*R$zAk zX;cj%VUZH~{G;vHzh5jedU}N_!Em zRRn19!lC|Abl29}s~@QB?{q!<5;&Gu|BBzJq{}k~W6JX?0o!lfBR+Z&$J5-q6uD2m ztzKZ(qa5%3q<(QX^f{6D;IEBEVBFwio{ET7%Kvh0<%fxK-KuTr48mLh!F6y)eyL_Y z8W!oV5~-N6A2sF`nhAL0#l;2)e+UAUqr%CjhLtr@yw&1Tq*!7>v`gh} z+)U*XA+=0>qS4z7_h#Vn==r{%`>vsG`y!$no%JP0^6AqTqBBVM&#WdN)8qj9{;r)q z>=R})ITipA0EMR?M9d$6RJ4`z&HTaN!`X);vir-sO-o+@$D%|ElT{>ji@dUb%vTS=Lq31FFTZM6s9_EvTm3k)o6Jp}gbitLJr@H$1W{swjtPz3 z?PzTJOk~d4;t-m5qm{>!4cP;&I}eqljKY>=zi5V3T>)8Oh8++Sh!VQ$wR$i^s`6j3 z8ge*;X+_VO&FiU1e;DlajXcZ4pF^QL;7aPkkA9Rct zp80wwLI1pb6|Tw2Z1UrAA+8Lh7}(dO@4Mua%8%+!;jD{*zB#Yexq)WAsfk_VcdhenafA={#nhmV)7W6M+AX($j7b^15he%4o z98kD^HaVIM6||KyclX733G>s2IiBCHvH%+Y%NDH1VmVv20jHyFV;daov``OD9KUa< z#m4oKcdFJjYOi16FP--KDE!pe7%*>}!OkYB<($aJSzQ(szOP6GG;j&Bg7Zfwy49L0c~)XTtp?ajcf@ft$o;qY78Vxj zIyzr~LtKPoUVvJ>3Mu(L-gKz~OD@uTb=D}MHA|F$U{Xb_ztK-UgXS80L z-%Ly^Q3@?UBbTS66g(WGwT*8JU)JGk{>6pPh^B^AWu4uHt@zD6G`oHbb5tfr0XtmF z#mrYL@6ky0Fc<85{Zp65IdlZmX9;Y-L?s}H>3Xl1roCWwZ3V?HM6ER1$<~JFB=<w~8|_n_YmP|mikZsVR~Z%sAj{kw*{1EtTC#+PgOVgth` zZGz_c`GU1X7O&8A6`Shyfh&c{Zu4f>rSMj*M@?5dC)?nTXF1x=BK53n-nLitd+!-w z7`5_ZL|935Xvq^`1i`qH>CL#bPJshY!?Dv=iJNh~J-A@3ulWr8oj+!#;gk{O_FSH~@2|kNAkPoN^Q`D#ip3Y7S2hw$g>OsTRy(X3NTVEBPEKC-^CEBaJNAjaidx$g ziaI+a=e9rZG0sg-d%L>U6AMIvKYGgdS@GHf?u|vPv$Jv(AI4y+t4ApDutw2DieTGC z!uCVls+;_Stel>1UapPg(mFjFd*aj}yBToxn%~J$?fuUm@~1gV=L0;bKyq(=UX5-x z)Q1Qz_~I|soyM-K4WU}^KL(I)0N*FyF=y{?bP(5fIAN&kw4_PUs-ididQPoNvEPcr z@B<>d3>%*%onkd)RbcN8LiX1+X1xXR)&ABWhD+;_uIo}TQ_o+Q#7 zVE2(lHB&muHj2MT;0K1#Q5;t*Hc?maxWy<^^lamdmORh4tO{!%A9*+&&#io=fO4pW zCMz!2i6~Jw3lfu8Hm9-P=McnNz$aIBg*j3XKd_@XUJ*w*NSEQUJRP&HM;j1dhiNee z?mRD*j}Aeqtl+v|U0)hsW(!OQw=+WYo+5s{du}5o_|7y&G1!4D?_%d%|CF%;F@Bk6 z52I$m92nq6JsLT&6DC#b9E|uwIZJuGl_k-dxS(*gI&AlT>LZp4-Jr2UL^E|D4+AvQ zC=4sthK7%4Bns*MJBd~lTXMns9&pPR_E?mI^zYrAttHz5-(vqiC7HrDy_goh6Yx%T zRU(;O=W9?T#8}sL z?Po9a{yQLs-}*%RC7~-}Q8qm9yS2!lT-JO^^tPAZvdJ&}Ly+1p)$g%c!b8fv!J;Y2 zy+_c?&eYX+(hqm29K^D|5bF+!rG!7sy>A zxc#>iv+|lWLU$e2CJOH(rE%0LFbY)yR@jrDOdOY(Dfikk_I<;4?cUXU>aaf0(UQS%tn$HM`vnc;kPQ0$qA7VNX;X=`8w zB4K=ApqTpo$oy#VZ_zv6v`(H}+-T^(`m-Uc8#u4whvn~l)&0N=cNAyPM3}iBL#zl} zprIq{C*B@~;Sk=;yw_)0&bgxLr%TbYd5aMnByRnReqs+h)Y8X3Ce)vqvccpVCbMyN zp{+O835EY?;P9#(M1lvQn%2P?IvoGgTlMvzoGi&C!Z%AYWAE1&E>?bZL?M>EHpJEg z7!I)dq-G1*8njr;;DUfoLfWN}33yitjHVS_(%2F(q6@^|a09B|VoW=7tlVG9$TeQn zdtZLlSAOjQaHiZ2GEL;bJ$?xc7bHkjh{ft0zn;>D+4h4-nt0(<6E zz2*PVf;X*jNNv9LUqx0keo6HTIgoN|cGh|8KIb#*cGa<7$Xf!5O6&BtF6Kc|o-+v( z>VHmdN)w67`{#>4>pX0L9LBKNV@c=I?!CL~#!GeWt}jk_goJ?NZz-vw;{JTd=|Z4u zFMOni*8CA+@iPz`uKD3D8bpH8P50YBi1m1_MDX7@lG?);^zVaW4=OWH?K;X9v;JXK z3Vu&gK{hVP3Fa8YGh{Lfgs4nUO|xI_V`5nZkW7>b>R_i(cbIV_L5*3%O06OiZN{u3t5l)Xu4JoN z$y%hyHKu)r2WNwNx)bAZ{CjFTpT)e-^_Kob54o?^>j}O$t+@2%$0g-M4MeB?S$!>!!1f5L}WTVzzoT?vq?=Ks!iX6sV7@dF1XS909Jh!^NFoJZ0+<*_KT>Pl;CmgWS z_XsPA4hBfg#&aAvFMjLUViz$RX}tBukC(y0hf+2C2S<`oo^RGF;Rf25CV8t9F0qL} z|i*p0SRsKDN=i)35u}RON5IdvITGwbZs(J z-jg2Uw#w%7#};mz#R3PLRJe|rln(#!mpgcZiOdcJgxT(tSd!#3rJUy?Oqwyv@`#C20eA<^h!n9Ge z1xH4el6!Aw^C1m8g?G=YJDGRAk`dg}$|{-p8ujQ-daH04r)v#zL;Zihb3C4p!piNY zx!Z4fh*5g8@H7T$>?>BS>%DFNgT}sKdMfs1f~fNo#g}Wr^M1dyAW9aOEHW+6XeQFc zIvyk&A90;k?xrvPRxIG1!$AOX1$~fIvm?mQ)${IdVv?0UImr3iVsSo^JY|DbtSYzPmq0= zf*e?768-%^dq$b9-{s@x?<5bc{GjZ_xbL4*43LRg?ggjeFx44jOT&1as@$R$`Qqq) z(y%Tu+zIpuYZ%GOQcyN2?jzwKEd_^U4GS*ijG>WChOx=I@))bw9Oim!{>=5xd_G#? zG=v#`YXIUM;_^CF?sBKzxaB1$aK%2@RJ^5antw@fckSKjvp!_IkJ%{-pkDJ}Eg+Wc zE|r{JkZuy#A03PiZo{01oPt+8WQpdOcG>gR>WWx~;tCn4!whFlmJ&Uq5?N8}Y?=al zfeTWC`T8+%er~$f;JU3(AmXZ1%FLHfP^5oTXS$ohPadbmuz77P1uhYck<%zVsQs@? zZYi?ONDE-7hl{)_P1*u`-g7TWt2fx5UTTx^P{oCF8{rww+kuIpoZ`8kDA$YnFJw=A zSYdI7^V*_+(r^!FxAd_VmK1lEn;C84f^r_ka2+qTvW^A#A?cFrU?z>-_{fu2mx%G2 zF?#Am&GS&?PUf`}8%l-MG%|07%1=rCW$F4%7M=Is?7IIR(07*`LSeKZ)uI{1C+LGX zT3`*n0?12uJOvTh>cd=Lk^j=owQ{7$n38ccGX)3!?atlnyp5)|?0!uvx_sy_48mZ6 z>_%|Q2Mh}%nXe$=Z~OZFd+%L}_iBHfl*^D7O(h&14!6wP7kPedaHg}Xb#?PQ+W!oD z?BD*^mQV`=-mv2>*5Iu;H`F11Ppr1N>D6>0e_nr%VmS?@X3d*=#5Z7tM0FW9E8HoS z-SyR%IL!z3l>Y7R%Vk5&K@3RV8z^L3Y2R(=eD9?OkK4u4Hx)%XE~O@53|3P zo`1!$*Stmy<`+0q7JiJtOI?OR&Oaq=w2wsb_0rXEN&l&V$zlokxo zMW=4DH9GO>N2C|LH*9(_C(F)SHjS|BZJ_n+oZpbNDRVD(@;

0@18<4nRPSTYvt^==ju6y;wao%oLqh38D*Pw^_p92L z1a5i8LT{B$L+B4J)oRICZ<9L{D7*Zr-R`^C^Fo=8o|6qcfd=PrXP7Rv(KHOtR$aJb zDwBa~BP%85L3sJbbGBXo?861kVqpX2Rfx3~wBf6Lf7bhID2b`t>F7^_J1u;%R5BOLYeo@CoRS!%3si&Fg*M_p7a zQY0NbhE+Ht2Y@Z8=zToaLJ6-%(o&Buze0>rcSQoFGI<7iRb(7Iw5FVTKbOTV?}Jeq zJ*8VFw4hYkJaxaP!lan$IyyIQJE!qJO37CBG2g_5K6l?)+5|63tV}>sZNSn}r7C?+ zhxQTj&*!JV5QB0;Rf9URfUy^xAX{GPAZ)$1CGeEoJBF-ej-FwMn)(UU$SXSuFOGiF zVHh)3jMX?}>C^^u!6CscRxt0lLBn|7PRJ;1+C27OsGW@P=3WBf{QZA#_aU?ZFY%=?^0$wKhL|T#!LUW$u#+eydZ; zPeaWJB}kj^?%gGFzUeAK|E$V9jzr;1>92Dc#Cp&NUVpzNC1bHjc>ol%My57}*k`FzJupD*I#M4cAC zAd-RCmwqIOOHe55W7wnf<>P$ys>;fMljseCM71rtf9i=yTv2lWl8WX&=}r3y;qC3z zzx+OEbV&Affv~A`>9lbIqLk44FEivZQO%{p1Bb+Kk6P3z-pLC3ta#eKS#LeJ^Qv=W z*_bQEZwChA1k+Sn;F*(dhc4Mo*qBqka~pg^iDmv7O&! zWKiAsT$s0?s`u=l_U)e@-R^I*|NCt%{K^`6HmUQNjEczrI)VkR6B6q>yby(%vEEFI z7hCwnth|?E0nT-ADXq| z=oP}Ka;nVQ6GN*KbJF$&$+ieeDxTpJ2)>2R$l6FWQhe-g>_}YAGBzj04{@X%gY*!% z4b`g|qgcMoUaY$l<71ra)W}U3FWtxdcM$pF3t(tHtB;tsi*!Zwsss_$5~KuDD}|GgiF{ zGsd;5K>osk5bsob7$}?7dKF&S%c+Lzvd#)Y*xQqTG6OA_8;T^qE}u^=_WG}xcCR9x>TU&y z`cAth+#X$$Ms~GdNH|bz6%EHHdxVJ2{QJg^Q(Ltb{;5lGoCHElNE}!+GAQi#dTFKs zFS@+iAP&xrjQ+(E_d70B^m6W-Pbr_e;EPzluHDx7T2ixzSDb&qmhm5;f43O{gzUIcXA}0a-YWI_2 z<6@7Fo=d)c z`xb9WH?y*`vaF&aK5!I{MXEM6!aLiL7o0EpOzR+qUqZ3`F^BWi3S-GDe=E0_+O6x^y~2$YmwT z#w0@LX(lE|3{O{95yx88iviBuI)tsT^Z1SF1{nLD;#Mj*s-``(25Y*DdAtH&->mJ) ziEn4yrQ6vxtNF`6C0S)&+1Y+p3b+jtc8j0>lyy8$bKkx;JM!K6wBK{~jzC}5=;8u_ zvlwvBf@JHs^*G+|YmKb@TA3Fyo6s2Y8C;8?e|X5aq$nARd;HJ#JWbVD+R*ale&-iU zxxfPz|GGLovmm^HH2cF{lBu3S8IVRsS*C8ojjeHDiL=b@T`^AQ{f7nQ?HAR*vb#ftkYv+F_cZh_xMz z@Gi?CTAU+>G^2V6&Y$TH%PYv$Y|0Bu$WmDa(}o_*RYH`{X5-62)AFrsI*iz( z!xLg@lv=oLyZO1kJGCgw#3E*PHacGM!-U5)TrT+H!h1hLu6UaUXGph?8Go%lbE>%V zsl!r|nrrBZaBqt}FEdW(`Bf;Q1MBGb59QrDycjp`w}VDExmwb`H>W%bFJu$&(n}G( z8&5Er-UO(7zb-eM#YF+)a$sOh$fa*XVug?dZ(iurs2cwxwwsuVR{pJCmZ5duE;Dm_~ftH#M5CvOT%N|?0LTX7S7T4-#8dJ98B$Mzd$kdVoZ&!D2_H4x@ymTV4iZAx)mja ziR+!u2wF^8SmZ?Jp2$m0F$*8(9AkaGp;q6y&4EQ5`_)iBGQ;ti!#Na>ahFw`69~E% z#Z zD&0I1Z3vyOx>D#RGmRa_mddrZs~B;UFuO>0V#AEO_Gy*tizJnMJ~l`87rk&amGgUu zXIs?%k3Z|KNdAM^(-FiJb?ucz@z7?Y(^%=hL9Zv@f?*uU9Qi+=BE;}d=1XWvQgIs zB{mKYY|gC-jU^q!ZZK&8#M@y)&Ss}NV?c@{Mc3JYP>t`dsT>IXnr`vpzBwCI{CjzM zQXR&qcypL6;%ABr=&epg9DdM*l3N#tuh6uTY0L+c9E))@Cx}!&AOV1!)Z|!o zJc6KdqL8wGzcLrEX*>pC7JXj>*k0Xptfy$`O(Te1h~aa1vRtx|IPKrSXcyA0tH|=N zYPRL+i#^r|wb~Hzw{T+XL|pTtj`kC+794dZbci=e#eM)kj+ll;1+}zWqpy?(pIqhK z$mFcU?gW<O`EF42b+5)5 zsuvbNS&A2|o`c4_2LMtm5d2!JSxWH|lkw)o37m@zqc#K??G1CoQ{iTh8VuOGxM6RQHc-i})1S|q}#^{-KnR&@KofN03NCyE*L0-j1M;9Xo1_tWSAE=+7}*ykeoC%vMyc|G(U*R&&6!KV zE8@ZS8(_w$zx%N&NA=UN2cuJ8kU+0)@Lai0&Nk;g;@XVhk{a5q)xEV##I{+4;X}OE zDP#DeBF6%-r*KGS&6op^Pw?nVdDdT%7J|iGTWr<{>zi*E0n#G#id-gw)-3RLQf1z4Fq4hIb*Rl8LEt#Jo1&w zo}$t_5}k~{Q@#H3CkS+?yx2PI`2somNML^r5};RD4!#?OFNA5I<{1mqV3~j~Rq*~X zdI}xAl5i;xA9AjDkU>2_cXxK~UGQ7V{Vd$jw%5v6RdNlwQ`&#?iIR)2=sns+_AY2* zdhQ&qaG3m+sx8Dg{jnAx8LD`#WY=_Wt!1VNu3sdy%A|TdfljHv;C=j1U~?Ad3U9HT ziCR}6a>zzSrHO>7P`VjFr(~;1K2IamuyW~FVu_^uCd#^BDmfmtb$lVF;?c-pL)izo zzu9Q{xwt?0Gb5Crp}P97#Mjdlqap-JSR$5Pk^;(RFN>2C^_=$k6LN3l>9`**L_zLFOtf9(XWD|V(g z%ivY1NP|~HinGo8>K^OOjQR!7uuPsGG*=hI8YSBbTt0>lcB;L3{40Q=v4UW--VendYO>|F)V0l2wgg<6s!bPikSfMY-SIcXlFvXSTp~1iP!#v#>jMT}!7G*l z-1>ZXbuUmENv*^4<|LGWp`Y7oE$MhS7OO9Ht?sC+L&3`V>2U!|WAojI8;2l=aV*rj zfs5CGWY@VigF-M3$oph`CKfgK_#Wy z4a+j$46L?-)`K`HTQe!X#OlU$SZC}Qcn_p8N zpHcZ`*w@}z6HsaMD+lC#_VQ)HgXTYdo9vg=xNRA$B8)~(3fO9p>hr;9E z`{9X|TlgW^f4k#+4cHi5(g%{o)o4VnqA=&=_V)R|MoCc@?zvg_{ypAJz)}G*ynpL+ zP>0w*B`F>T;A7EOV48sd@MVC6jzg*8p_{pW=;6hjIW{y=ea}$gv_LbqJyaLi4h^NM zl2h!U@=G31isO`)S`c}qGThPZ+S)#82w~+P?igc*nbxf2X#z@;cJo@{x7JEgDrO5Q z;@uDxYtv+FWethDnNIzj22tgZdqUmp$B0z?R+u>I`D)Fh-qo7}`oV)szpWZuHR-(8 zli*)-)+QO;sKeQdpEAdNGJGfnvQ!GQkaX6cwa-n`vkKV%f)B5u^R}-@)QcRkHrJ>6 zCw}~}BhM6Gr9vcg+F_pu&-;WepEO`0M$;7cWuw+SC>|4<|133uzm)O%hE&Ig&^o?s zO^qK!9NSbqTlg9`Nfwu)>u=tK*Ss3^XO5a6hJ8r|H?Uf$5ej<(_2X-%PI3Te=fBa{ z2cU&ipAVywmJ|YWsihNxlXj^=`}hR*%A@OphPv)vCJ#~-bEJAnl1}*hI`jE@XBqsu z#E%_bvu}G>KYwQl#o8 z7{~{4H$-f6cIlopC}<-MBKKI+m1x)miP&2OXyTs_&fObb6|{)VTk}PT8D+i6F_6eX z$nHq|*tqzxFFlv;dHOyu7FJx~URQ zS1l_HOzhr|aEGb0GzT^n6j7bx5(KX|nH_Y85wnxq{2b$Zj`m_#MwsQoy?$+?Gf`+n zt!fS}j0bMWctNI6LBn&s$dmjo)=sG}R{ziUcaM^`*Z#c&B<*Y}Gz-f;E4{Ji*y% zq<1>>=5M=A;|^6C3y%SE26y?Xuhr)ildq?q8hcI^(9z>svkE1E&GGL2j&S$O04yA8 zU<4};thfG~9KUy|>IvHKD4p68pn()o96w7sc=BOpQ3uxZ{DJYp(los)A`Ob7bx(@J z79fp{A^L;dOiPmypYRwAqDG!M}2;|Dk zv1seW0KN^IE#$8VjHp0SG(M2P{baUjoid~^|fl`~#zBKdJjbDNR_046gG zk(4q0J})slI0mD)3Rm1zbhlCd>i7awr!-jdUM|SBH)!@=Nr-~QGCa;wi#Mx+hpa!Wmf3a1$rOA54c;=$AF~ss@{ZAG zg-twgrAm;6mCx-W8*@nc#X`5 z>JqH!7Rs)BHwuVLF+GKQN@7r>?E1rwM$y{6ZfOR$KZ7_vxyA}5Z^CxLbkcKQ@syRq zCUv*YZb0iCoNpFL4!*~kYb2l(G6As$(@;c+-bYj? z^gHbrhgZ!Z@7|U(QdWA3F!xQi`QxPV3KPoU7dhnANn8iwC{qgWv5&G|0(-C|$vy}t zAV+O#+&INroINLgi`gMO7o99XhXXk~x^z6-Je4?J-X7go<>|FO*}-o=Jkb;`;CS>) zLQNblg5O&G|0DBt6pVAq>p{@N=R~v|-*Ky5EwltgHVNqRfI9+c&SBF>9vvrC09QJh zj>5vQZic&)|Flf*TyDADJMdi$Sj5iFfH8l7?x~@S+FczVfm)4 z69op!!*$_CDv1hKry0*D^X{V@W!n4T|0a|})ET5Rd@Z4;1MO8IfT;6fAa{fl)7Xc1 zFIOb}WmroHUT3fgQE2crLylr<%HnQ07pfIF4s^N3NM}YZZ|&b>+E3$s&dY`ptR1lE ziwhd6i-UwWB{i(NmQwQ%tw!8301mLr=ChSkNg-vQ!vk_$f(N8el`%A-%qw3{ixmcP zb)E&~_))VfcY><8Uvsdik|@zNv+jQp=8buf)?*YTR=9*0@6<=?|g%N6}9jQ;YDuKhJ>! z&4RD=j>n*@F2{G8=C2veactWC<-;jmclU2;xr0;=J-anM%<+iYxsM6tkGLhprVt70 zl|-MUv8BE_r%8jmY~GL5Kn>aU5U@P;EOHWWEkrROo;Ss|S8itVzIlJ1HR$|WR#|PB zLXhMOi}r|UN7cOUJSE4J|Grwa(w=LOmjLK4KwIm3<-`X=+f$f}bj@T`Y!1x$E%CO9 zjta{Bl$7Fl;+}U=jz2qD2HYLE@*um8ON0vQ>d5cf^n=l`n|l!9yZPDe)zKZp`TrXt z3ce^$qtujX{tA4=pU;-^o;}6npguf=T9op`7u|SKFq<`QzbLOqaxZonjz0oh2BKCG z$;l+Nh?+PJu|DCiFj=G`MQ^xb)VgD=7;0GHUF8UPNXo@<9+_R}PbnZspw#8qkCjNW ziTXT#_4Y9ZeDWad6Co~g2(7kVn=kO#D;)lh0H$%gp(OdUQIqD)Htw6)%~e9Nd&&q+T5Iwi{E_Q!P%6vt#l6^PSP zDAXueh+$y)5)sSR`VyUB%jO5qw6dDgi~0{sGEP>T(suaAX5~7~FCO#KU`xHMB5?~* z;n6LOI>3|DKIENKzzbFe!&cGIkBD!}1$$e@>SlG;+j3v`!8&RK&PYU0jeQ+yZXuiv$=9hy~F z>LNV*A9qQjJpufwfdLc>1%Uupgo5T~sXax4-iT0yqKVxi_MqE@Kp^B2(goKjAT;o|-3F28m z_td0Qff$u2fD@C>t=@dGY!7PB^(bMF78IhLZrhRQo0!*%K{{yr>$t-9>7Gn3#`g}H z%#R=DZocgCe$T%*pExYgx2p4W*7vP@q;XkgTTz8*{;DAS9F!T($ZIkkCnHkwsc*UU zE$)xZPpqFkRbZAl&kq@HcKYT&vu#8uK;;)cQE-}%(QaWqvm(EsP4sS%en7liiH{X! zM@`pdMb!{FiP(gt^MNTT84(>5J?xN|*|bn#-Dk%IKS*XMYY?peRC8lM;qy6 zej4lEvtC1StRKzLgwf)T0~lZp|A=f}nz;W}9K%gO@Wl>)>9%iTB~3D}oYX?MP@@8q zA2+u?6)zcCS(_#^Mbdis-;o*}%n&O(661^pqoVabSD*yL1?0jNf|$dPiQKE5$@fvJ zcz2ugbuqkZVO1w+Vl%+NgLn9+D2EQV6W>}WJ0nJ@1=qJIXk6Wp4CM<>7v!)ljD*h+ zd9Hv;Wg$(KoK~kG<^D3P$&C=3N{kU?ww(RN!Cy=b3JL#6&8{Vq z%po=@hv-GBQ@2v}(FM-*AK9|q!i1fMviBedS4m)sNuLtT-1s8X7}J8>fEC6H7-|>N zSn`rYm=++l{apwWt!Gt%;#`6uV9O+?b;r?J4L$t zR+P>Gly0R{I%Qx4X&6eR8>NO&x*Mch1V#{$MnD;*Luq&~p6@umUof-xzGAI&ogr9; zU}k)_NwRmfkCtum4+S-C3 zy8rtpKai=BRp3r0M34IvVdvc2EH%~THouv|xv%-(U1k3H9nI@)RRLzp5bBUm_J_5n zaFP^^@DE6h@PG6P+OR~A2A}dEfQbYgCi^}29BIS=P?CH+VLLNOQFoh^^uPlp!WqH_ zPI`7ufZ0S(=v)bPJ#JV5s&hsrYo}?nrJ@0e0s$_3v}1f0OnY_%JTnHv2wr zrA`HHXa9f0h##ebtREt_^ox;Zw7##9r*cvmwMmvv3>0z~=px7)V6MKAs4_oqAxy`u zo%06hoy-@RO&<{Z&mu1|ZFZc|xDaz|FCZsd?Q)S?kz05xPS&!nVEf;%gjmw12I`Xm za>exsZywOdCbs2hkLe9Q9|KH||LU|y@)NAoo*uf7&UEx;s#%jDRUw-Q z)69FHn?DBPoLa;B4i$7{>)On)m#>h7?bBGV3GtyVDN8DkOA&b@u^nLB5bCYBQ)Qk`-`?J_zlf4ff(Fi%UI{TSzX&y^c1T z>;o&`SgMSEPM97G^7{03N9Es-&!Jn*Wq@J2$<1dcfG$KzRG~m{7B_f~l>1Fz-fxy3 zrz|Y=A9a~=0n*Mh&pF(F{PtM}c&IVqQ3V8In?-u#JZ)9fe{`{e1yL_au^+?O04r6_ z+N1z?`3Htf zh!_7;M?i$D0D#l3>P`|_NazzP5y!$`Q_l7v1>m5q%SJq5R!*d}hPM{Kotn3dYH~M1 zLQ-~aws3_A0$ytMBSxEPpfiy}o8q@yK~)(cX+J5VabLMPVbm~` z0^=jq6X;~4m@9lC*`DoN#TYS?@DST#ML2ycnIN=R!FXDdiq6y(#Yb3<0kM6jeZ!YJ z?QLHWO7$Q2SnA7rE%LM{PziipqlA8}*5eV|5UT~BQN$rK^_?L}dt0yBQWXQ-K!Fa? z<#+7xZFZJ4;HJEyx(_Hd|5uVDjYy=%>c4vfVvncgt6$_NDdyt85(Tg!pS%T4pOlo- zyOX_OV@N|r&pVk(LnM@$e~j7}S6@7fhMRWLzep((eV|2h0z}X);y!Amb3{S99f)c} zQPpB(b`&xiRHv~taOu-UlF>^K4nmp}aHsh#N!q@7J3$4H5C4LIK|=W{pyIMhTS^%A z=6D}1)iO%NiT+gLc(Zd#$&r$+jq)T$3xf6=^z#WA-7t&)l*yOu+I4gEu;e%=>RYoh z+jBa>>?&pVTMiJITvQU(nAl9KLFECu3sf~8(Ik(`j~e%l3F|7OzS%K5QTo?iDA{x+ z`aa16M=W$|otatNlRGncg0w0qSgt^p8NDssAtW^WSRGY1Zb^awe_6kJ=6xQmuO#2* ziw7~(@P-qpk#V>-HGD6RvjNwl44h#0OW1kI*s_IUoC)k9f}!-W9rO33WLLbnc|JQP zPtr4BPPmEsbPGBu>7Gc#TGhbkKf9c6kf+s007xr;Y-;x9r?=I!T4D=7nibbIall$! zYV$q>L{hSVo3^dIen3Y&xof9;JPjXJiK3s$=1Vs#GJbC;woh+UHM~(P`zjWfkY6w^9DQ=k z^(iIP*s*Mu-n-}`q3hTC%F=fY!=V%=_@I>9&^Z?v-CSImT6NRIDZV}ZV%ZPh|I)G6 zP`()THw7i0DkXf{Y8L&_dt|3jPcl=mW0JmJnih`8 zLSlgq)gH!jSo-C3%`H=$>#n71m%^v@1)~%!c(Qa&*M-Zcqt5~oen*^LKw`H6Y!{!{ z+H$P;Zwr|NQ}zGhiR9qz)BybWocbiTRiRc>QA@Hcd5@78nQfr8cy{4Ew!%!NnBDY) z)>kFY-@Lz#TDysCo#$3Iu12OIy9F5o725l)>RHknh^zK*l{0zgKfFK|c*mzOXcy_| zA*8TN=lwuAwpdh{1$!N+QPT?kk{{%EggMF!yL6;ilC_V__X?nomIx?fh$HRDQR+Co{t@IC_}XR1I0?{Bw!^T4jj!~jQbaG5aX z5e_`He74#m7DVQNQ)aCHcr;V{)-kB7`J{-s zUhz1x5ylu8hF2>?{}Trlsii1dSOl7Z^CRFvCqkQ`-Qpu+g6ia{?cJ4u6h&(%fXe1n z4~v1?kq`X~M~I;I0-22!MNNEqdb*Jqa>bD$Xo3JCVE4f_A*GNg=K7M!0|#O*Qbp`R z^EvmP0?kTl&Uj~f1@ylb%=Ps?VW49F<$_{*h<#XC_5sq9>J54Ap@P+%zxUSP%If_c zT+~r8OV%$XYZYM&%xD>UXOX z56lLiU*LnquJe|ceE?e9s$ym6@a)${A0OA%Z5e;(p_A*k%P-b2-vxKx4aDNYbIuBZ zD(EDQ)>C39-LKB2u?zvy!0Vigz+Z|64y!-5mNt=UpuACg=8F+6g{U3~>oHpzHxHkf zSzo+onD*_ZSJVWRrE%uTIE?K~Bicx&KZH4wk}jfy*T_G%D--DjMok+wGrs~PfKF}$g z&`5WmO}pds{xU+DBopr9N)CSk2Ph5v-JEq4h1*_G#`tn05<6GB(Ig0^LIMyYtm<_3 zvnN5bLa`kptyR>%2GHr;+dmaGLqI%U7jheX^~b1N(cAk`@a5v_pQe|z#8F73!0lp` z@PC$zA*5osXMeS}*cQ_*^*`V|;#W)AN%oFF<~wnzUnp1mEcAJ*{)Ot;QFOWa-wVF@ z+V*-qW6=0vDs~-{+uoBzBUYV8Qfc{d?9ON5i0Vc%Db_$sp;zd~oZ3|%{<9?UH#Jxq z#Lne+s~*6%2n6GIrS-H;QtGWFHHg&%!Fz$F1ZhZD(1+||j()&iKB4th-`pYORwI(g z?f~trCAMu2g(1s{9u`bBC&R1S?f^I9vh)cmy|+K!>27eK~w-!!Ej6WduFco1QD@iM4Uk&H`*=B8Gy~r09 zp%)wAu|NY?Z2xw`4fxjv9}%SZ8Notody2dX?HW?yuW3&o&mzgxm(o(nPfDBL+&wq> ziFr%7uZEL*x;Qa-KNX0H?`w{uFW>T@9a>tCL3FgzIz&%52aFnp6mvS~d->3f&+$_qP$hj;nu&f^V&Ybh(Sm%Q~m8 z?1C2U)ZLfM`>3y93+B2^9?%aioi){&`DvlDqgAgD-p{{tbuSt5k$eziFlM!)^(_+& zy6^20K43T*;>jZ*8&-p5_SKITa|dm`^SF^LAoIU)L193l`??ZutW9X4)udK22<^MU zdnAJsNsR6KEVAVAsgN3qs>2kBX|ok^aRql~_G;HK-KIak<%Tu>Z>MDioP zKO9En-Uol8GOG~8!&ObJRHl+;0L~R1_Vm8@(cFO%0th4xhjbP70z1(1G^X^p60KWEMABT77>OL_39- z(J`cp@Ms|VeR;ETvXdH_R`7P)AEy0;$e^v(A6XIoPJgMRt*$j5<88eVqMGQVPJTi( zOE7(Wd^{kA-4vYu5kkMA6fZ&g2GDS|b$iEg@>|Jueo4Ak$8#7WKl*-a_9p5X9)ydK z)7^dU+eSZ99@~mFjx=HInIkW>{fV&mUD!aA7-}vn4SZ-pnef4Y?;a&3ojw%Rzzf}<3JDQJ zW38+Uw`-epg8PHp+e9AxoEo5k$q5fG7l}N0^*B7((LohfQc%GqS=4aD2&ts5)FX~2 zDdj&vmO0`BIgDHn2gN_pe}!{&%Fqm|<6#X-uHhK1)lbCx`8&$N8CXBh3HxH6 zvh4(_GM>wi)dP~ExtFOyMr=ZuFhJ$jgfutaHcWeTf1tt($C#4R@c2&5g;w9$4V44) z$Z(iu2{=9@;<*EZ_5q2?aM^YEL#1T`f^L;r5=#?if>fDJ6M-0{MH0Nf4E zdtNlEFeZPj5~LB`2l;8%x!urgB0qx{-X&}>bhw+q45@$oOdkmLfVf&k)~R!UeqytLX+;75KbZT7TvzJ? z>blwLf95X zgR+1|)ST4%{lc5onGDWq3Uzc}ikId6@1aB`h*>p??RbN9t%5o}5k==|>H_&azdF8D zzp`Bj`7&?K8O4*W9gU{B}U7!@P3#XqvU*Ljw?OH)|vk z5bt&5kbZu?R2R{T^j10Xu^-bII$dcsiMhE4Ws4P|-GCVdz{(wWbgzM#HWs8jcDe?M zg&4Pp;b+*ShPUX0+vPXQ!8Qud!hV^lANU8CjIRrS_&5sw7q;yBdRklPCx4X>TnyBT z*`iEfdn4M56A=@@Z~k7=x-jWqgBLJ7?Cg#?U}>VUP*^S)TT+~SO;~87seRZJz$4{Z`J^2;&ferx@ERlY>)i*CwQ0II zBl8kx8#}gUGJoSVYvIhbXLODmCE{P={U?ZlI`x~EK-nN6uhS!*s5}533+-u|PqWzrBKISNKqA;6c<{I$J*d*zTxf26aX=(;OlB` zuq_L+*@yQ@vdmrFnA)vjV2P*qIky~cw7~HO^;8&MmBv3c#tup=0=#wCUr9H0i5?OO zsu53ab;+aO2T%~IfPl&9?VJ6ez~Aqd@gvxcB^xkXEF}2G1Kin`k#w*HX(@V&k=zu9 z6<4~r!DWGuN4G3iZls94UkmZPb$*9zFhUx*%i#2^gO;mm&ZrBj?2iz4iHPDlJs9SF zd}UaL&~`=PVcA^wy*e|s*yT^+go-yIv;&Y8_u2DnsSJIwT<` zwBTEyI)8rPxseGT!9)~o__hNFV%1uVTf^ekd!Z!MdXlW=^qWcX!I#1Zi!s)`2q0IN z6qc52g3H`E{)G>UHq$<3ej&8?!m9{=a2ua)pqKPh*=&{k<8w|Pn=%O3d@xSKh>OxX zTC-n=Z3GV#? z+U2&BerUSMu!CK3ciRAk8oNde-}gW#*z zcYYG+-T3OD7xWI_ySMTJCeVqgVqa>62WsT%Af)%h!3YH?(Ewg0yTXc#WusX$(tlB7 zh1jpo9TbSAeJT##LL;t)Gp3kA@JnCw#{{P{6OZHTRkla4_^II^sEk1y@)3~d-2bw{ z;_O(>7r^I3X;MqhWY~8gvW4{ln0EDt#)QjBT4|HqcjW^tett{|c&fEJI5uiH$|k@2#T@T?NNX z38h5Lq21sGz(Bd?_PrLP*P6U#+2_98?fK-!ykmZPU0B=RzhS=B?B(resw)*rM3o=?owEx4<6ddgZ0&+&DKaqifQOxNJ5#C@}ANTj{Bx2gq76-f(!EFAXB%v*9sDv8F*P``J4?h-MJm+tn zl|x$>Q!P$=z$W#SP+<>3YZY;1sSQ<77)Y7b_>3;L#_gvluC%8#uh%;bBv9XCO;vFD z&}`b!mI__%N`D7$C4SBceUu8#k&O1;_W+#e9l6DLQSWlNMK^%INjw}cg!TZ57l_)E zcI%5|R>7<&nnNYQ8hD8Sn=?EhY`B{(y$p$6STL128sVS^v!L4UcaI!NE&YFU-Q0?b zik^+?1S3FmI*lKx=qV9VQ&d|^4wPF%A>>pA?GpEA3K`ZSH)5w+#rX!BZ?T$h7$k0R z4}Q9Hvvj_{QvoRP@Af+2bgJ>GiI9{xwr;gXY)^#B7sn%A^-R~qyr2+ZHw>aSmtZTle*Sv@03|&0H{~riNb{l{hOblv`F4R zXEzD=U~2e^7^I5z1nkX@KYw}9SQ&#BR5Cdd57UOkT(?P+>YHgE2|R6b6}Pqj3e>$2 z5I`v-i5CjoLHZmTegG+ZT4&zMiY1VlsU&+t&ORG;A*QDE1wpnvc<%hy>@RF0!tBF> z%+D1s^^n1?{--=j3IKs}52)76{~6 z6?7}ZCK`P$VpVg7IbQ{|%O9NoLKol|4 z^1d-i()e-MmA3EfwmhG022`&qcXNgi@;;+_S&v!KX7Vh?9$D99fD<_(f8 z013d!**Uo>At8bEP8EIzge@$8ukM)n0@baU^Yioni|D*_VgQJA>*Zd@M)la86qgRy zF(`;rQi7hCo&NEvR`g!#y;Grd>-Ro=U!M=(${+n;p9uYKq92=jbu^`*K z$|J@3I&oipSem25H+{!N-k>JkCZn*3>1*--H9gV!91n?W2D(e4po(c zz}P6CD{wNIL*?$xA}YpP-cP zTrZ+!Z$bJsyYwPsRZ%f;sEmT|E1EtmIovPBKyBTNzAAVck?^u-dwcdnKnpyQV)*R! zqXKw5NxX5(p5O#2BoqtdmV7oobbsG1oFtTFcw5_cxxKx3A1}0X$#-gHq3}%F8sP&W zURn4=<4Ba&_G;y|H`W!K7vJi|9`|NBZ|C-Yiw5P1CvR59hM)7WBsJ#uphAKz@5x;$ zPii5@)O`(3&8{&zAJHEjCc@Nx(Lygf6S{T|32v)HlCGAU$yQXxp!S!G3yKNXy{V2M zs`Q?Hh+tS@uar4v&lZn(NK^L@rN5gpAF-DQQ(_uZd30Xn-nRa_evE0`AwTc}k}G@t z+UiGJ=9X&@4dkk`>NQ7rwNlYfxlgTS7`7OUa$dwGQjr@CLwQ)fuOa)LhlCdmLmyt^ zkqkIV4teRVHy2Hl$=s~te&L@QE|8+eG|pHeYH?e@Z%P()d7z*0Qirb1ac7|uZ)g6S zbadiLQh;;aqd4Cc|3^O;b+GSbss1F3dB5>5?!-lAFFQql1aJfYKcL?OO28+wEQFD$ znVIxPpHJQ0EUvSaP)keZ8zAE9{jDieXweSmyCavLT?e-=Ple$CW*y63+ZOZ9El~ZH zR#y*|Kd(s2&(HU~{tfi110aRn^Jlsd_w^NDbPLe|wNtb2=dg`aJAJNz!CT1fwUoKd ze=bHA1=TlS?H(M_x46lMhs?34%w*M-R^`UZItGMdEhcBC#xE?yzFIbv^8B}KV7&U8 z^0{q=o|&}S?CN7TIg)SrJp+dux@OWUU;o`Kow1oR_&*G|VKaN(t<2Hm8mXfE}isTMz%Iapp_L=<@!``D&5Eu?c92lK1TwzLk}B7Ct==X25W;`p*-Ww~W5xYH3>< zkMUY~iQ=W{gxQA&e}le5zFYZYpfMcA-$mbxjojEMt%0=TdXAoZ_as>5bum4L6z$TF z4bJwkU3nW(DRQOibvU#OZ_CU{WAA(?F3Ig}Vrk>&vaor&aCq&wD4c`d9$4}_*6Xl- zossz!e;53kWGF#87Z9@MT#@OADi3G1e~1tLjqeYVrapiEoYM7jzTO_F&3daXI%)x` z1?d3_w0Koc1aN*JOS-tYsP+Hr0%V<^Ko-rx>lCWG&VbXx(o$YwNjyl)qR@Fekb3@2 zoP}S``P09?Vz)l}&@=uYgT_?Hc38DkXkGuqEr09lTg)GjoEv7=iiOtQkMvI&ZRHxm zY)0DKHZ~gnp5ms`AV`T`+~vN>O;N+np2o_a3i`rL#h}TFT@sJ6^YQ+= zY9IX6rl=>yHE#Jg!s5!$TOB-$1ZGfu@W#70dfsvN>wRVRXIs_WZqmzDi>D&g+!(2T z%sl4R-~LT9^9^V2f49?^lr3D~V)4&F(&S9Kk$!{z7dsmQj zv&ZsVATuMnGb_wrTlw}a0t7Z$gAgMKzNA%?%bf!A&hN1RoVLJ{16+7e2~F*{cOuT$ zN25G25W|oo<44&INb-lbH>N8 z%p+QhMiOr%zNa^fk28VjmG>5*Xqn_u4$k8p5(v9+^`80D3Q-0)x|Xk7=&jN^oPavr zMdbsglKBYRbJQbtPT>Ljwo>N?2Rf~k=#%|AHzC5qj>E&;>J&~bPG@|-k2g9BjC zN9nub=lDnNyVKLlujpGqXw&Y*`f^@+vsk{Unqgp=WPis)gb+9W>8_%{RmVOTa}6Z> z9hZ9?i+E4%t4_?spR(huK`#mnc04GdS^;8&(i}mLw27dJ${+*TNcf;m9-}i}p+Lqc z)+kMG>3Yw%kNc%)oHGe`tIqYWiDS z`LIUy;-F;ND}^kIdqK2xbaZ!RfBfYIcn3w_;>LtK1k2j*79Y5?pSA=wBFWvON4;iW z_5Ai#lV6P59U?y&vanOzHub|qpZOm9~AWrVP0H?b71e@QC*r99HX!Sn(1c}5)B$~yr~g02IW=fWs<^f~DjB2P%Qze%eAAJnE&E#t9j(e3EBzc5 zba6V^Y;7r6DvS*QP|8>PAOyl=zGw!K@%lqNk}M_QS+YG0FpzMl3QCyqNmCa3*BPLq zuJe=8Pk%?vV%eEICh+tYGuD7+lDLEy&K>AxRY1iXL`onYC0?=8odsoe=R~x=Kbu~I z5l&sJ^msASKxFsxjJe=$i=#@-BMdZltm&&ZnSAn-=3u5YGr$G_EFf~k9>Z@@^m;eY zj{H(GM_8(7%y#-dvysz51-u&FqhDLl{{@&rGsx5K6FvZmwg~RgLR+la8)4VG8YQVG z%Lo_NnzzJ;*{A4^D%u33(F9H21`XUbDT&x852+%6cG>B5h{!(n!vS=&EibIM7^1YN zkojT3l8dpneoawy;I&`EujhPvC=Q0P$Dh68by1?GOKlABl5EXq2W&8hYQ;JIa8mqN z=#0VTKtOzdf&c6)cKwcA>eO;wlI0iXRI=!J=x`{@c;`Y$&8I=I8p~}GVJaUPWOD{P zN9tPv3kngVpyqw9S#L*gE$Cbj?R^|Ae( z(s#upbL5mNsqIb1OYTWNgx{x}VRKqL{!nJ^AiwZ&g+RRt~Vu)hrnl3ScPD#rSrURCp2Vc>1=*wvXsN+c))Yot1R6&2q z7w!UUI8q78!!+IzTZ3#c=lWAS zLZ^440K2cistR0&Kx%)hDMO$AW^;d9Tr>V2G=#hEvpFz)sZ?6TM6&aHk^=Gui6^*_ zC^x_;9_*ZMnniBg!V(QCD#+or8~^Za0)!);bztjbs#gxmj;Dw6qiqB@C*a_yTXa)6 zgnh5r=SyVA24=d^B2a!Zcnx2qFqpz;*W%==iDO ziT}i0JxD~+J_BXYNrl+UF)Pc2imgNp$eBGQ9M+lZf+IU=&IS_%$hWLOY{*JHa#RTH zt~pf{nEoEK=`~|EwQc*=v{?J=;#?cM%IB|D(RP~m7#G+l8pgx_LT|67U$yT3W`c|y z+G+-+s*?zU|H>%QmMrL486OOkG@T?0sFKO%KdU@r1awd7Y}>scJSv2^i+|^5@gs$r z$)uWE6Vt?8fx8^XANL!-!lc$WeGC6}lM?zbiMif$f}Kk2mh!XyL$h%U_~*h{4N)^0 z&S_istYLEssOtj!m)M_=l&Rnb;WbbrHPkLGR9t91asUGpx-XU6eqER31MIEt>?eU4 zV4N6@1-ihU0^Wo?mH)6oUUfEO#&b4o7=s!11SOP()wov~=yP&B&lOq{DlgH1JCk?E;ez@6FQcWgh6h2WOD$cuV zNQMtYy)LK?0rcm8Pw235NA!WXR#raR4cK*Y28I~pAuKagxN!ht{iy;f3a@RAJ*JWo z#Sy)$?ahb+7emaILea9<=K#fTqx8csk*8nSGlnxWLW(EO+m zDoHF|IleH`TKr~r9YYd3=y(!lzdB}YvsmWkxHA*TF=iE?Y3 zO+)Ho1+`(e=rOyVFM?ei03w%8{Zne@x;eNwvWzxgha)RZ3D*ADfP`d&j%82f@77xH z{)K)|4o!aezBy_BO$5eEJii>XhgW~E9`6{W{QIs70lSj@MIUj!R5AuT}frM*c0(3hk=@qV!* zP1$8Y#rS)_cMZ_8sz)-J^42$2(7=oPS(R4GTb^hxKR4GlTH*zeJ zdky7BhZQggtln zi?cBdW`@Acj{Wn&V{-xOj|9IQn9s+e`-OQI>i?i5n!g;#22~*&b>?*D$iSkTjvMMji5Y9QLN>*+PcwzY-IX32l(0gR6$`jBH!(H|KPpv zf~cS@(vYc>4v)OEMKf?dF+z<3uI`LFaI!;@ThCLZ;9{6L%NYyT^+|?td|&!n3k4%M z1br%YqF2V}7mt@npXWXkB>z5Dj68)+^jfVpLcE8|;5zXSj2-JDPi&Eqg5IBtUoLHh zkhcDNXiY3$;o}f{DSBu==F++{=;$+ z*156-MH&wG(E3CaX4ZI4SopiFuH316&!A)@>}Ylzix1=SlUfAreGDha&kQG2FELjp zN=u^5pNzy1_pvzqNO(P(nq13WSW0iXOY3`ol^?gbcyRGu7IM27Iqg|!nLlLc0P0f> z5~=-4;FD_Sj3r>PVvGCw$sR$|rE2#hzz~z;B#gnr#<^aS6Or@W`smOtSj?0;$&1&2 zr$_iYB^{w&{rsc($yp^c+P^0+irTk4PkJ}*W9?!x?sj%@P&+R^a9Rf>30h)mhW#KHyOZ6mwI!J!FGb=-g7@z6!yMU9{5Pu>4Jw$sQ}shGlY4 zp|aF24Uh;NTHa&h@I(MBhdQL=|_Wzfn&o=fH(a9|kuxV4UZP5=O4(UV#_j_7Q= zd&H$gQj|Wb-9QN}wMG#=;JhFSbPvWMr1*sGGY;c{;BjHq&m(6Pv?beq!5KA{gH2SW zKOf6TB)T>={dfa+a%P8AsozUzZ%O6b`+_9!@jr9Eu!(LIKnJRt#|`FUxSC?fszZ&4?oP&DpdQ9R z!Wm3_avlVS2xbvhIHX=qWJjA)-wIXTRp1K>I8nO%1X7u69y9qW|9dXY4bn7HMx0db z4-%A0$|)uwH1%th9n#PL5sI(K>Q5NmsMo*0QyB0%kgc0BD9cs~p}fy2vMH!}JwcD% zqNGOBp0r*KhDl2~7wKTO@5BOX;p?^7%~PW$2z^Udh*aM)rDCO%MKU!%`f7l_sEbSt zn=8kjEfyIK*GG9TZw4IWJ`Q%YDRM<=eMbG&MF9)%56EoNQLx7fuFJq=oC&x94TUah zzd9-}H$U+Qus*YDEI6pvWejJU=)owusuo69_iWK<5Pz8Rgp*K8LC`Z*m@6@{DEh;cl*mTyP@j6fVR`MpW(2GyD(Z19p1-|ZaUAu! z;lc2gyL~*C6!hj|pzIkKtNr0i5-*^|i#xm8B=AR2`{piG+IO7jqy9FwY81C-r{y1? zV=*jIAqJO$2!$yHR6y)F*R6+_w!P0v`Np1TnUI1>-#()OE$whgs~LYK_xCBia5+1! zR*hb;wrJo7_cc-sV!ks#+rsPbxsHmMF!>L|^nL$)#u^gVzOp0~;MAtYj+I6khoppb zA+50~;5=MtHT?1sbq#9xtIV0ebWwEh2SWcvinS%n!WZM$#?MTBA~;~la6Yuui2@!( zN`=zKDK`E>CSq=Q z7gXj0W}y2R+&L?FTt^-~@S*+I8#fHMw2ADj&g1y<>e%G*c>uOT^Pq(?c0D~w5XzaP z-O46gv>YjIM+s*j6@Mj~WWbP~#`q&mh*lxur<@AEg;*dNoP>~HnQyP&74=sixFI`6 zCAAjl#(}BxXAy_y)@{9T?SNs>wwaS#sZcH_YLq0|8(FyU;0a}6R!C%Dek^i7k}3se zrL5hjDU7j5*D#B~eNBpsC{Xf&Fp#_5K$DX$S|zSfz7jwfHtCK{I5c|MfvD@rii8-i zooyek&iRK5QvH=p#CeYD(xpu za0W`1Nn036yUBT*9AP^RrK7sCa(9d}p+8iV&j24!wSC50>&bhon4pfx!h zA)VTZy8TWdRRhote&DgZ!-3FGHWK_7$BLL}F(Kk+D}9K)T-J=cT=WT7_KO$PDajco z-$a0xSHVB{HnZ8r8!K(15@CPd(+X6nU_}kSg4Zup{#HVrQ~Qpy!4`mS+0pBJG!?wz z$lJnT>8`K=^m!g&zcC-S&T!PaVRv{@5Hh+IL)HPQ$2N48h zmeThthR-5+RLG&3HAo^uQ?jBiT-n5y*0EbHT;&e#vGuNSR~?B{Tg9qsjY=fZ_3pXH zJYN&&3B$FwXa{J0Log8&`iSb?jI4f>C9DE`gbfMReQ*$;Pb#}#rXe3u9RGVi(?AB6 zjX2$ac8)SQbNZ|?klpjG*LBvWK%v{U;=OY-=i47ZxoseOA1fD(C_Wrx7da8c;%&)VL>hcC3CFw^RI zIL(q{;akv1BRjv7ZUsk+6W7OO{{Q}do^$0xAJuI;*XIPut}&Z@ zz%a>S_@ni-5tu8O;P(`yTy4JHvG59C$7Dz3QIjl=9(~F#%BQOnRmlpZ6$4W4$oGay z!?zTM1&C@a*f`8vZO;_3ep1^y%sm~uSoyAwQ1&sWCT@%r5pPsKxH7m(&Hj7m4{8b9ZN8`rZ=jNRbe7ag?elP5XwUF%05#ayrpdp-U+2xo(6qn_ z#c96IKM1sHKq4nEBaZ&QHLEgtljuno!#2j_`Aug zYU+~Zp^AT4BBM+-NS=njb%Ll@Z)JpYnNQsl@Y&FMe0$*PbIyy9wwiWvTSwl%$G7)P z$kXW=(AoZ~=Hu0l1_lrovRrrEX0=OXY+|B8!L}MPC_^NnJQtKW1A3d!lRtbwCaMD` z&ZKQ0R%#o))qA(?T3^3T@}d1`p>u?wN?sN#Ls(jyEEQSb-6h&kM@<{poV7;#+L)c+ z+LK-q&$H(c!3V+jbY;}erOFU;ifPvUsNlHoQOoB&5kxBHt;}3#B|;EM+tXXlgX@Hp2ki z0P%1v`qn+vQMUVEXt|SSdH_sJpaE@Rr6TS>;J@e^+N8Q^#O?f|j}ql5$5JQksjr-I z5F)+%2sYxWz*!{GYl^Gb@>MCG)Ay%&(w7(}+MW8#QhZ+lNh;=R-`{sNSxP$%FK{|N zsA_-TVzAsmYlR%?>vKeCPOKk8eWPYhttPw$T$^a)lCsOB??FqrSR*&6ZdL|F(awOS zQT!@X4qNt1y&}FPYcTr*cfO)nM0M<-MNtQSpJNK(zG=crsCeOuPlSN(+8ZGS+tlpR z1$CutXO*>3G0B*VIs{^--N+O4G8%AL?(gtv!$5BW6}OKZc=Eqn?}U5weJ^kUDRgP@ z7W0J+Tk;sLM3If&R{W>iq77;fW~cid>ecZ~TvUmFs&47q^&+6F7h5S$)o; zn10V2(Tt?H!xFhS|GlBb$t8!kiJ}pRyiI-W-QB@ds;=?g`QsuWSkgruQ+EGHzzM>p zaU(w-KE#i-#hiJ}8r{;mtsB0lTZ0ccX?5!hgc^`YgNnlsGYS0tJEt z^coOGD0}jg9ZGFy$FMLlCEqcGBD7N4M)wjg&-9(;Tok5mY=;h%L<;i#iThj{d**&*^_TU$bWP~~I`v5k zgUNP$tsuK#r$LER4|&WR)%RjJvhCvxDrf8kHmQ8nHkMET1|Ji)le*8knd&c%iWovC zPrpBWnG=-;FCs?`%TkDzJ*0Hs+rObcyCmt^Ue!L$;|-^b?HI@1)c>E3!UY>QY*z<@ zHJa|hWh_xZJ})dSg?lBjkn&nYT^IEz37Nly@8(DS`bR@gQA3#31ollp&6=*}Lnoe8 z-M1H&1VXcnzu-O}DE@bw0<|=0Oi`%`R5f@@&3c$>v#tF6^J0abF`>U#ZKWqxS&mXh zT~)H&HKph8mXVF8$zH*MvYznV-!oN$B}df03Pp&CzluiHcakN#F%Gog6gef`iI-W_ zFNTv+G1t978%obwrPrw~vE8^N2HB#lDjpXhGRl1jSEvRH+~rQD9unMduF3ngRR2Ck zr_f%{NMl>~<)iwg%hQv+XnkIS7%b&ifNLr)ns@uSb}uBfh2`6;CXZ+)4W4A5?0v4f zHb-++^AR$)K=QNUlF;rD>et&UJwHNH=WtC!nRGC9YP80%i!2yx-(wyS>=|C4Ke!`P zB1CDRbEU|DqsTn;{%wZf%)%mup6b$wDu+0BkXCVXP92v0qfzhm&E1Dv$uX%%CjGbn z&a=a|g9n1m;06=M@m%?J)$wgY!z-VJDut7A*pov43)r0Fcz0O(V z@Tq3DXcUIm=TWL}!i$U8S1)i660;%r*cL1}xdH~d6-a}>jHnheDMuj(eUo}5cDu>a zlhf30i<*x5OhfD^dpTEizZc0wbqkSLptRveZbW#ptX|VC8-*M`bMfAPbD4(`f-e-b znJ3-+K;ty%0rv1LMahr4+mu@!6Sbk*mTrutD@wjY`ad+LMIXseR^F8}fY(0R@Mkjm ze{IJ{!kB5c@3y@qg}3rsxPP|`2|+=Vn3#uKFIb72!+d0{$z6Re#P;;V^g7wd#3#oc zIhP2a!PkT)GAIiu+lZYDoxG-@gsV_KFYm|`j4ke9*b(k#hIlrjMIZz2%wIV;tDVJb zcVT{FelUfcr(BD)6_}d7uikLa-S}155Dis z2Fdu1HtIuqqDwl~eGKMTQNZ?p#Lwg-FZ$b8Tu4hbheyB84HkU}#)DT}Y&#I$mWMw( z9CToBrGYVuu`J5=fBg)w@KPdaCw=57DiCr1V(=C#&a61tV%^8af$7V~``@Ja4W%5d zbf}LjLWI73kTyTO^f(o}*OAD;COv4Og3!JU{Wk*qFsr#VVW(sesCMp`ilo4?A%fK& z_pq1i=`r#U^3?U}C$JzduG$;3p382v8_W0gz>MKuA@COZk6ik@qjF2vL@Fk9u6I4J zLX=ZGhp4a&SN18?QQy2CNiFr04Du##Q`Mdhvk2xDeqbDKz$2s!gyt~}By$EtxP{#~ z5-0Tsx3w&2nSyO@m(N~$@Ag3ePH(~^ih#^`aQHtmEiW{bgtj0H-@0 za7;e-+Vh@3b-<*DtCcMJu0(yB0^(wKNY_3(hBb9#3*RO*zXEb8&a_(Jqtd8n!3t_5 z2S3R|pR_#fZUG5ii_41Zau7Jzf zw=1|%=qxjk~Z9|F)+lMZ^73l41`+?ZHgM6;3nfcqydfxac z)abnPYYIWOL24>1V+ro^6}H9J#aS{X^>96BM>zWiKETA_75SZQpk@s!eA4c*sH=;xl(4+``+jWnXsIhL6OAHR)-A`s zNO~U5O!mL?@w28WL3;wIvFKaqC2mRm+|4O_(>XM)jiIn9U9TN}hgAD>&9z^2p&dTS zx4t<^&2kNbo(J}8A0{!fL-NGvl$tek{R3e;uOLxmtfIxObPnEx?fS6+>^QkAYu;lU zlwHOe68ApSzNkL<&QtZtp4y*5wbfzY(c+MF=glYC8Wf3Iv2Is=z9ol{FwEpXInZ7DM6oj zG&eBCJd|DISQHBuRBi(#$xbZ=xBPRDqbB68pKZYm=4fUx#iY060fsJst_qI`< zgx&>>y&YAy4(JjA#Yu3upNR2yj)8G?rgXUbG;7+qs1izS(~FY)da|}b`ylL+q=8_H zASD~50^yySqR#@);}2ZnMZFPv7lJv(W_7K!_IpZ`<`B@JuLPG{KRS{y5_2`n8_T|-1z~0W9*wGp`e5b17?w>8>z6v{Op$_jYA|ag0Bk2f20z|6c$mY}&`9ix* zUVh)R~mQ!u(S9opz;qASWc&wM1F1lk#x;H@;>`G;ImHgIa zwrQ19vC_E7?3*dw{y29T9*m3~vY-sW(n;Ds!?Iln*VcH(z6A!#1BxW4Es6oJ6jFuk zxo51on#nILYWxjv>?aWaHQOU9RS4GE-O?io8|SP|a0WM%J@7O#t7MA1=fMu(!yOL< zZ??}h&qv_H-!|c$pqsBjuBv^KH;2y~9FKv&>|}By#~js5q8SB)%J=BlNfseppJ!O> zNQrOf%=6^Ah(W$qkHOrmmGv3*8uHCnm+m}kjxSDkxn~Jsylo^rrrG^aVjh(~2*+ z`$%P$bId)#f!J|gl6bohY}>sW%gjmND!*Khp8;1jpe)d#gM5ze7sl@SE^IIc0jTW% zWU1ojS7w7#aSqNY|@Y z0WT+{GYhKoJwm&hR~PS^*AfJdpn8WW+R<>;j#mg0xt;P#@gRFT zrntCbl;J&$^ILUqe<{6Er%EK%RvFsB%Q}yLjluBW6&X~gx+zS#R3nruD*GO_>>SCc z>aHUR&aO5F^nHUKK{TMmwUI(N)w9c zM&4#ve#iYJqMv#StXb%Il|BjQcOEXR<`d7wwVL2C06MiFJXbq8RbHHB-^0A5eP zen8WWy7~Vb1O>c?NUr^+5U2b)RoOVy`-<(gaAb1tYbHy2U1OBFNoA)eq$ko?bvVjD zOGupUW*qbTRubo$v1WfIAXz>&Qob)O-}rp+VP7?CZNGqHKT>wZl6_0|SOm20i2gih zj;&cb@?_KH_tZfE6)8&C$YN7E=SlDJCQqkHvBE{X$+asVQbm7;Di0Q9i(;z;|YA20~u!UJJO=zaCuY9LM5yBr}+3cI+zwxr?Le zbrQbsyaVxPPotzt#-D5Ubjh+P<&HQ-KV&J(V@7;iN5iLZL7Eh_8Q=*%yC4ci0iVOT zrhpsR(#!*jt~BbeTOyyKq&Tg1c}UxTPv{1pMwV^WlAhL;fx+4bfP}yW@I+0qi;kv` z)h0i>i8W|0+({U4q_FDVlInPImu-&SE^}G^395R8kbODFeh@Fc-JD7aDCn%Xp}a1h*z)|7 zGqf`Ne2em}>tsEML!fnkf`n*{ybdS&O~=pCpUJlM;!#5fn;|+zp>u;44;&C%%dF;r zwQUwmxbipeE2MwSNpgq+HxioOiQYiXS&Q7?;_gA)dRQYo4WE-;Ju{JO?&y5>e`5q0 zOvd-_OE89U-nfl_d9I_#ie_DAv*u5W_XIQS(zoh$s1)_%8j)8{*;t+}(FPTCXsldQ z!%dT(YwIS`i=>CnnQzQ9-?iYhLdVN$CWZY@GtDaeUpdePaJ&KAtwI5l$BkB z&E};@%@EaVZgo|Jr!E4CUj~ie2t)|CR!)K^a%^5XO5Rad$gTV$^%`4hi?(zVEPYXE zrV;kziW!9w!K3!kkRE=~=9h+=S&meU5#~~_Kkm#jaHRT;%~KMsZO<7wiH9xeL|6*X z__8`L9ryJhI%LrNUs98{I82nNW3{S1iCxJineiJIOiz!(spZNVw0s^rOkQ)Y7{K;H zd_QEBYJwhak$dld6b%|*Bh!^O z9xxn5$?Ng^8w!wYC}vmjRrU$88dzn=0mqlkN37zeun1h1;jn~k+_h*|1y&VE8uS-1F57&)RF z@xha2?ymROPQ6rW%T;bgZOWR9l(2*Y1`eJ`H}}S!GmFB?l}fLy*k#WZ#zr9e`VQr8k(M64%g-kwvQ=^NJdknm!RTm(L7tKfO>RZo@y zV3*(hNw(&-7l;nC4QGn?KKKGQ+0|snGVdd2M}|HKDBdoJAL_!ua!+>V~hE$k2HgRq4IIKqAZv6ti)7(HvtlMOWnRY<&!mI!rW`-P6 z@-svu1Z!)eWi}Y{ z>qAq;=)65eL;If75wp2Z*#f#wn`$;w((qeyY!+KL8OMD#u8`rka59K$5AXPV67HCN z|1siur`cNr_`UzJ_lm;NWRCet8u2NI8c7Fwgw|+ArflYZBNHB_Dk6?rGz3^`Rsn>u z3#cSr|0qx_*S6kqW%=%l{wK_)fipZjtY~G$^1vf)rj@b)TzZcl4bUW7EH`gQHun7c z+WW8_<1xO?K==e|!6HPWKR2X?;6jt+8+F}%5 z`y<-zuqpD$FJgncP_!E~aZy?XXL+^IB%vYV^lI{D#$}WP$Z`n82KyRCvbkoCOf1Q> zt?R$^+D2Z<{j#s1Y}rR1_5`~^==Rpp*Vi@F%$}*wSd9S0;gQkU>Xpgx@Fx;3&d$K^ z4yI+!wT){W9&UiyG-J$V`yqL3u%BZqEqSG+4qXz3jX{x0HefUy2O@P((e|0^!MP}8 zp^2?hRqYhDx_0yR@9e^_{*n-MksB$*?2|jgo0n~~P-?-qSR!Wor|kGL)6`6(f^`- z=S;EKYk#i3u&{6`+X%>RL7T&63&C(Ft=!Ny&rCV6!i@*OZ7*C?<;CJ?@I*y#e=Mi} zjx8FZMF-v(%Qyv0{L3d!OTXGTq`oEUH%Uv(ri;j=Cpaq@F zGOn(ChK4H`ME-!R-w}pI!V4@`yNj)Ki`NsiF1u5FO}EDbx3KOtYRJQb{Lb0U-QmrL zbSpEuay9f&C~D}2YB_EtE;VGzg)ry8y=*3G2nu~4f6#OblM;6Zgpf)WF-bQ+!zw2; zBF;1{?dyUm1hJSRQaLM6Zz9G|CsDg0LN$s*>Q2I&CH0IYz*l*Qb)@kuL)khZ^lh9> ziT+hakQ0nwcD4H2(cRTksv<+E>inwwz=6U#E}?|x;EdRcW571fH^$MQs|@9%z9y2aknpY$n*+ocbGZTS^~*&jf9E<|0>(<|@9%C5xMjnAn**j> zrNx$4P-_ojOvaqQXlTfHSbzfMlztmNJvDazy>L3N9Lk!XtG7op9pA8o+k#JHQr5$E zP{!&2s^6Lb@B4d!sXeDDNZ2ikx%y>&o;l7{fAz=mesS_&pC0hgBhXPNWy0J0Zp!|c zi)kddzFGEuEviu9lmhqvWSG;drB>EtqAx56$kGQ9How zbSMa#7nGnwMDSZs(PiHC2sW5tFy`>SFCTN^!wBM@&3H_=+Tq5>>EohnhU#Ip*jQdt=u0!ut6zB#>9jMh|zUQFLEMi zJMJ!kRQyVK(T`+$TI?sX7(DNRog0~VYBIETvRL&Fzl_Lupyn^CZ;0$^zNzD*#nS^|AV7krBrM4#d9KQE?pM%_ycku0`3%IXT3>Xf_0ytw?Ne!$=`mg0z5#eiVQF7rOj z^EzPaxwmcytXYgTc-Fxi3CQU4>TWJIeytj|&M+bw4;BC1chDX^;3oIa6oLrt&Q;P) zbKO|p4T;4ttnhl4cTSo zl8<^vvr|wS2^(X_g+p1q6Hja*uE!(0;|kI+oY^zsF}G>S_(u?CJc-YVjQBGjK~OhR z_R9;h4msbO3-8fRO9+t2KjXDVdG}5%qM1JytutJPV;=D1NjGVM*Td3g5Y!|;E7qAddHwQs0`1Ty7B;7d1EO4zQ@VUJ{d zS`^bdJm=v%yb9#`y4*WV#uyss32`Ea(amde>)^$RlJ=s$ClVQF6yC6Z9QFB4UVP$Ww7~u}Eh6_c$ zkaqe<9pv-UCSr|(7F~}U>1;GukiiML`G!xCbl`4+aFD;JzQ}MWS}IlTUE6|nlgl;z zarA(eQRBO*o!A0eB#5P^F>VzSRFiK>JetM5ASAOmpcVc1Q`e=%2-jy?K|f0jS#2#A zJ@U{*s_61R_<#Z`o<1S`i+JaiVdxtN{yuCMLl!8`zP!3 z_b6vFwhCkql)Ddp=v&fZSCuyArc@=ZcILBgr0>vw^lG*}5$z4JY6rSt3#Pi`k`88+<$?f1vEec126y;s505|Vq!R1-+1HoN&*id5Vd zCOV+iY`lCyd5<~8#vT6cgjrYfjm6K+f1UQaOTX=%bm}iU+d*+;x(2CKF=dra^<>HC zfr0b1CE7>$LH`0P#miI-k|7@P!TtNU^A(kb5+hBZOdjWQL{(El4E+ABrJEvxz=Wi5 z8HHzM(eBPv<3y7u1fTq0-LxagNpz~wiw6P+eq6JIN7D`HCm)et12HVUv@{)X!$&pJ z*3RP9`quqh^$=6{d1-Cj#obeubGmCLj~UZo)xxI zy3RinNKKxCb;%@U*7N>I^7p}rN*k}S`EJK-Lhb6L z`Al5Lbj8yrfx#uS+fNy-Ojzo(VlExQn~Ui}{H@%I^>9X{p#8+su=qjO`QB`~=Z@~9 zXSQzpdpfT*E*1*-baup03V16tm6YHEb_MPPI(64cVq&EoMO$$HGN!E?@G@cM+D}CW7{%W4WaC5) z(BVL~Hr~kftoIJSjvjNv_QO|Y?>q9t|d>gB; zFM?C<@~Su22F8ouPE=c}%vKNGiSSyanfms1YRKtkURl0^K;A!a-P6f;bO}yQQjdwT z@HN;f8`r3a%6v^IN2Q^+-31_&wkWdaT1H0E(cBG~fw!x4SCgUb^szMJJ(HMq#@tQd zYoib9$N-)n3_d;-!gDStU@QD^82Gk!_GrewwB4!pEvS)S0&L!=M}jGV#G%Y@>FgYM zFu||ufT6E47?v@3WocF6vCh@jEcFDTIu$O@UJlnAG-yzYDG#|Oxw|8Hj>K~!e@(L- z3UuL1t8t4{Qmb@?73vlkQRqXhh>Vuw5}LkgTaBCh~BlJ7os=IAKCr z`HU4>9Vmih`MYHC{M^OLL266zPR5EO1({uR=p5h0TV@@X>(`K=5{BcIsirRnT55>q zXP6C9LiV5L*Te^036bZCGff>*>`Gb`>Cz-c*(yF{t3wq436reCaroD_#8IRN<9pKJd-bXJJUjRAJ?! zN3Poep7=4cupU|eMBD$I3tebGi^$r*eA%WiDZ-T8FemDd8zCsqFA=0dS~IY2Z3Pik zsuS;Fen6rj&zsq8f)y1VeY9IS(&O*H(iQpgpNgla-~yl+nxF zKChl8rRPwumuMzga*>Z*oVd;1^PxM73k7aE*;t^hC zaKekgTC1=Sr}*yqeL_}$e$U*`&mLBM^OJ5I(IdiJ7k_;$WY_{nbfHq4%1EzA=Fwzy z6RyvAae0#lR;7=#yAEiI-c4zgG%6$o5ueTHLLj2~@+!i-M2if%2uk!P188eP2ay49 zZDB+@@o)m|lds1M06 zvOM-bh$c9p(EvL@g4L!rdgwW=XW^57@3r9>;bmPeSdIG&I6 zHjI_s8ah!}*IIFJ3W!P{b5UNtp--@hSBzH}XaB|39gSpKN^ivUM?|=b__^5%LYC@j z@LtLr;~v>;usvtzd!@zng+J`|RQ7s^MwRtH&kR%h?(;y5i^ku~Xphrv&i#~-ETJt6 z=K}bTtMW4$cDTQPTKM%vzgvh$Em>u7ZQa-njwgE$@hJ*Vyw%V;^CC+t_T^M|(DN3} zEVDqmBK1_6R_U(NR{DW13Hncub9?}jG900yIlM!cQidf(Z5bpctg$jNY3c2IK2!xjETJ_JT6q>2ND(B`Pxu*MOwv>cUj8 z02|Ff@ebEZTh) zmBVG~BD+G~8EgEagBw!p`g5VicrfQ-)MY{E)RG%FQ^9gd5Ypq}fNmOoSpSWa7g_z= zmjgNptcuV+c6E|DE?-|i5Rj{q^-GG$W0)5r0Vl?za(d2<#~*_zW6k&g%k?j% zSby@<^gjQ8G)sCXVbiM_ZXj5{GPrK!owFKNas$?n3=nf*A%ajkPQ3dq;mDPOI-a7w zY-O9d13x|x2B#ME6?Ll2?Noq0+f!YKK^XrEQ8fB{D(qYqyA%lk6LUu$P;{UaE#l?C zvXE`~0{v0{Ew_kpq0nK@32~AQaas#A`|h&_kl=9do0A^RNk!4eQkb9OEB5Ah;t*bO2>Dd}x> zehcytnXDv**J_40;9Nb1YY>dqR+LW;6NA~KeHFvHTrcRGXMZ7uge=sJY1MwRSSqc~ zU9Y5^TDpiHPn{_As z756B|MpBo=R}W2bs-_Faf?@J^iN#2P7-|IwkRN0J04>%E5TY~iE~5d2^#2j zc(lnSC)9s=JC7>GgL5O-%7al3EF_E5z6@A9i3TzOfw0WB$FW~8pUK5rLj_te@HPoW z0&~Qq3+TZrE7$Q)%VIM%JLgsxV(ttUsxL2bfG<{X%MGg`jKvh?38mncWQz#77az3X zruBkyX}h|@KHx-h&5MsThMw?+#>a2tsQZmAcTql<8$XKbJb!o$U2-~gY#i2KqR#hx zY{AhcIVBy3AKZx_Hg=~`ykfC+9qA(Viu~`|vaieVCIJ~3U0(vD&~&%_YqX%Gr>6!s ztngT-Ey2_RFKN=Cuf|>ZufBL-8DuTsX86P??*WYq5U^Q%?gzQ+(wb#B7`j4GiQTh+UUT$38k`8FY|+_nF$JiIaDCJe}a5xR0o>ctU~ zMbE4Oh$Do_s{l=2$Kd)Vgj+YxkO2AMR%fEdU9#h>+N>jl7Uz1N!aGAINX@*i;`s0? zn$6-x@af{@MZ)3k^=v?XIamw=l!8P7SiPK|83AFsB zDur+MQVQxkc@AFw1jA>E(4DYE5zkqPM=f5f#j;2Y$KldXJvE}N zJaW%`3!N$gK<5T$?63S0;AL9?PKBwFmc3EupQ;&$f}az4vnU-3_YJ;}(@v?f<}7pB z>=UU*cp!WIP;;+RjoDW+BFrjrS999e2m%&B0_Z&UwlAl|YRJKc4dN=@yu7QmV7}~k z;E47`=NPav)&rkkS}k8+-Et5Aa>I-ZTQ^$ay_nemd->&Yafm+L;kyG{IwkL~Au1VG zyC~L#vfj?p_|1);^4jQ^g4uJvekL-3I1g2XF?MZvyO@9)pv1@M(UyWAeIxVSz?z~U zVAidjH&@JKU}IQL&3e=%S0+@|!^xf%eUU$!_;d=3OHU&vL@G&Q(I5TEF2d7{ox>>b z`6tR~?*=_~k{YdWUs zg5}-K5uB1}GV8`mZ#9up{c*l{kucOgT!;KRV9Ev$gX~=1IU3|eM(zb``OTPG2#Moe zr^BhSwM9&bQ*^)|HDv`nu@6WjHsOq%7I-7_Rt7`NF`(L{iF2yvLcvsPycKyrJTf{4 zW&bR4hHqdU-wf<`rxr=GItmy;x30%CJ))8!@uRShfej;CGUYwB(&cLBPICMbA(XOn$gr46XR>d{7Y*Zs5U z`h@Vro;nQ8n;luT+gW1=vV)SY{=EnRHrtuAsSeIHUuw*7gN%34_ZmLY;!IG4dJ+8T z7h59Leg4rT}4b?HqJ1PjOYJxX{ot8}l@b9!m^64Lm15adLJ3@M}_|g=o5@ z>IKqL=pgCM;F$a%XaFU;2dY!$CL#L;nMA77jxA|0yehe)@o8G^&%5(0@{D_i7Ab@A zyc^$1+R~2zx6^!Igg+A4GTHtK0<<`2;wHeKPGk7bP_>!J%upjy7Q$5tjnczTI(N0K zTt{RI+LUEhH7fG@=V5OKePs4J*N%EHJhHol@ESA{;F9SiU%V~AD3@r37!)LyKv_TC z4D!7+p;cDw50fsUKGI$l8b|PW`}07~7r?cZ5XH=1NFHr{Q!1FsVhPf*Q}j$wcx`*U zIs&XWp%etxfSL-& z7N~F06V(+0xPnZdeDtjK5C!pHcyvi{Ri@!Du)q-1gKRFU&_3L7GbpPd>p)ZAx)%5& zPWI;3G!w7gqq<3yBN4*_e{P5pa3ci(gZss^NgTAd!4JhKQoTeV6tJC^tc%0(MpYGQ zbU8p9=QV>XxRJk!uu#;EOYNC3#UPw5H2NOTA>`iM?oo#N*0_Z*(`KE?8^dSu4sJ$# z&o<(%eu9k?(f=|v?C8<|8O(*s$q*=gSJOn`Rn#dlwoMa!j&M#xvc|rwoR(MF@5vJ& z_z5it?bd9?WPYNtj3wMv5X*JN>SMrBM>L zp(`;AThkyWR8^gzOtWGC*j%nenv~W+|H8Ha0?;b8cLuDCTltD49)=_(4FoXo^edx^ zTvqTRS|$p?bOSh*0EZViKpXtc&itTTx}3 zrESr*SOI_xK>))V*UilDTFP8ZR?m6 zsN6y|-4|UIwf=Mx0WMCLKSF!`H)SA_LDpT{)ZP{r$9h`gT+9#XWH~`YAmsAk0TS_0 zJknx74{Ur&SC{KO&dv+H!5MBVir1YiY3mLusDZ7#w3L4J01vpOUGNWSp7O zl4&bsR}vpfDo<=xT?;5m-XvjkA+2p7ZD}Gnjz;9a^aI2-=RSbRQR_Jfc80E@>$*DYw=6SH@l?O}l>2aNTYgXl-k?c9h zu6IZ>LG#^P|ML-KmtD`%Z*ysQ8G#W;v+i}lad(k15n{0@JPQd1SA<6{PSTK+U&d4!%n7j2;}fD|-ff;%lZ>7rH-vx8M^&tm ze--+w#Mx`dLQXduIC-1P1-D+JO0qJ?c4T4<-k|z4op8*b+b-0}a%O3fKH!1!rYTSz z0HPa>jl)ZB6bOh$Cao{n1l4?#87uj+x2=RI!loDOfqO1%P5&jibf_?Fv=qi+P(z2-WD>b(PY&Ee1^@DFnMG!O9us+K(YXe7fX647~J56hycA*yk0E&L;j~ z_+}h~-G{>WiWDF1-QWI2s_b;YhOHYXvP&Zv^&36A%Hlv6 z*EWv3a4wCj?V#?fxYEQSaf+xgq1zuA;neNn zq31vS6L!>jTsq53Im?P6MR(FI(V>cCtm~-{Yn8ZF$nyme&78GERCI)?>!kV913$q= zj3p^*xk}*O)^Sct5~1JEAw%l5WK0rR+8cLGoltzs*r<|?mIUb(k$A?OcQ*oepO7K? z<_DDxyDNn~JBy5y&Qy*c|xgS{KUK#PWl4KY|A5_ z`sf(|sYlH8fbkg62*Ay`P0O62S;kY^Zwn!NF!t}GS45Mv3R7+^s(vPL zXv)^#_PR3=$<}OUYNAcnng^1DFl-1l>;orHLjsMPW$ zE7R66XW|4wd@L>>A*jh>>D)kEEtA(9UY~`IxQe?hc&~hiKZEH5Ap0PyN*_M=E)Z>sc8ROe{Pr65u9N~4yDNeh>8oc z!TFX7LLtiXg7R)69Xs!L><`qp6p8srsF@4$z|dT_QpT9zpFaGb(ub}{*Za*rx5=>{ z0_LI@*=G5YVXiY&6%uC}9{8bw5Rv=v!@#dm>Ysgs#?w`U6Ae?+pJZIPE;8l&9o&1!`&8D$GDGCH#ML49_F9tZTc=6=Uka`c|9|sG+Y$rM{s3|1e_fZ7a|+? zzz62?d$$BkN|0SdL-psQc;UTPJy@owdJgr%4V>TA633FGA)p~f^=}`t94)=zJj^b& zik)9{n7VZbm3A6l3j^4ByEO{P`+_f%2=7$F<(>5h5qfSpGLLz=m7sTM^K4+IwDLF< zdqR}gzM}E>B;)vWaP$Y12+-Db5Z&^n&pSy^7+m1HyM%`xZdXzVt46i8)s-w|qAl7RP?15h+{ge)! zv|xHHV9R&-Jqn>L&Nr-v$k|`{qo1|;(hIj7zGU=TML1()4}M`1gm4U2c+t0q-Hv`MZ~y^)Hq@ArVZ6yVtM_1+L4Wx^kJ4{#nf4U_PLV zja+?1g0el%m-(hV^ykC{`W7@SK8A3==$1OvbbIMMhc(`+`Oo|Fd8P(So*m;Do?V>N z!q1zlUDuh*rxQ!`N^l4KHts@wzjVPO0Ol{;+w}h`@tx~DCd8C$f_-B_IR(Rvao}Ee ziKfJ~%#GF{D+e`G`(SepLaM7;3f$cg-gAjg*xoCrXJj5EOJp9gobn--=sil9+!7y- zg+{D2T_>hlL$J!a9 zj2J~N-?b=|29R=S+hRV3eZV3+^6KPG1EJ#GQSBE94qFFN_GIQRbW!dGGJTJyj~f7d zx45c!>IBTP1G=@Nko2)e9#ZX6=Ha|}f~iY$utgH(Z@Q;erY`$IwQn4-GCK(kNqBxN ziFM!hhzsEhliJ#*-=d6P(tu($5Mjf%J!JLWo(F{-t@-vBL;OtIhNTl48VX8K@0-HM zBmFN$Y(E^Q#z9&|<4%J=y{P(&R2-q~Z{0MlT?ybs@;*Q7GbE&rzVH9s!~*@9-YNo| z-knfx#Up0=MpTHs{>Xbsmmmzeekm6 z%Jzdm4!X&$Xz~JZb7Qe!C3~xS8W#Ga>c6M(xg8$KHL?2!fNN!E!ZN*)Tbr7#IHyAK z_ERy{+taoBytrl84+*_DSu9DdX<@jUE*Q8Kbtp|kl2Zzp*LAtSO44gN8NGu_)ZW-TP-%B)c_K`l^PQ^@UUFJBxmwOoP{qEyLcR0F`@}m&&;jtu)v+FO<(dRx-s$GLo{Q^-~3W0 z|G(6DqL~+5R+Ab2qR@L!NK3NRH%VipgkPo{0Q>|IEYpj$G=m1l_#I5Cfr5^W6cqNfj7ePcHhrjatYEolY2g0hsz(XC?fDkgoUU9uuT#LW z+}!mhjmQ-9Sa&~>M{R1%%N{Z-``JH4_>cDix1pXkx9A1Y;ytPXcMFZnmp;z1ty5?XJn!+)7cb0h6U>#unKih(jk@j1+c zAjAea`+lN6tAl#o>GDIaI$12;7)X_GYx{MFh)#1D0R2JA3D9`>(VCN0nfFDqF8%Gm z*yN6D%{5odCI3qo$ChIRW_xAh2imS=xR?7Rk>qDzJmriP4doxR79^ySL)fsJvee)8 zRE_5WwjqEr0!|OT2?=4n&!?p#fZp?R5Up$PWYmd2lGw_%psQ~jRr13H8r7kV9hjUs zsSp|Y0_rl=K<<-2cN?L-VP`6yAqH(6r8YHNX7`^X;fs3f#;?d-FBkI^SUnepZo&{n zJ!+4WvnxEGraLV7oqk7c0Zl@g48oS)AspZcRN?Se*FrQC;6}NexpzO-9V9x z#65D|p?#NI>ouEveQje<OXA zC1)u5YR2)z(UtBUQxa#42|WTvU;64@5^{Wl$Fq?h^yclNIeUmEg5|PM2C?Ug*?@e; z6bx9ns>4a%sLh`>UA%DqiN4jF4>|UwOT$Wim)OUhf)D_Vp4R|OO?dh}a|16*Ro+1W zIOGP7GA~@+0&^*!#;7;ULYKYa-uw{qcT+h5zD#IUzYa&8Q7HV3ot(j=9 zo1$zPs{mp{Y9}ju!Vj<& z9LY5jhjK**W-7S#O83u1ZKL76NvSjj{B?J`Cgs1z_-k=Ycj>musZ+!k&WBr{#$wUQj6elzccco=8V20R=8_KmCz^;;Rb{}S=rRsVM2Tg-Yh0Ju!5X_Pr@LA znlXpj^qzo0w<^{!YU&usGxOl~k}d0%VZD*YtfzHZfAz0FZ^KDQ*DL!xyEAd->apt9 z(k+1FM)7AO3aVK66(md3;{m`SF9_u~gJw2&v#pkwJg$+Z8oxP&~6H+9|4)yRk%< zHfYDid8&<@Zc^wqN*pDZi8Rg;Uqtx45wgA4aLu-M6w3yNFh>tSLh+s&gX+UMH<0RL zyCgkl+>|4QYFfM2ii_T`#FW=xxL2Dijt56;+rDkxG?;{V?V+|Ta*zKkpu{x`mAb9o zqVfPwb}-bR?DUu!^-c$)NHkkNvDnE?2AQ@14hLIC;q;K<3RxOYU?&YK6mQ=cchbY= z!U#4S!MMNwvz(Wn@Z^WpE4&6%j=PnLA7QBelmwA4TeL?cZ*$0~L{w zAPO(RTwmUPXRcCWqN!zb#xDu>)ljv^g@Id{LQ-Go{uuM#S3_Tel&P@nd(6Wv&Lywt z>JR;YzS=iFZ{Zpmbg{-dUvs~yDpoZPEE)Yx_2I+`y)B+x-!Ar#R%yJ38Kn|*gp@bN z{HF9Pf$=>}PAnHOqvX2RgSy!C{4CAg1FW4kZHE7JH2&4`{Oo(tB?f1ZX2 z86U)*j~!~W(hFP)57j&~81?#V>xKLJ$b;-2!r`wv0jadhHczE>m4g;$Y_DN?JT~po z^UFNVOLvQHX0VPX6_+Xgv(hGrRQCTP?LEWcYP-K-y?3IA2qJnHyWFxu!MS}=O=!Dxdp`ta;r_x&92`+tw;c)q+Jj5d4rd9J4>=Pi1gn`H)X3 z&i?bH^x)9iOmnTjGTkvVv(MswkwH0YILXEezkSBm6#J~F6|=S2iCMO&1L33fxse!d zCLQ5^WAbc<334+}&^jNB83WIz4hq%ZpD!E$}Pi>V&&KD`;jP& zWl+hjwC601|4q6K>X*rP5&B2Ni4=$Z{gC`-y96f3U-p*>JXCs$JWU|zkME~f$Tpba zJzY-N7&46UK3$5+%1`wWr)%f6cLS8;ncQ;M2Rk{%qjbi|ZfomvyFHna{bBN2biigZ zb)6n&;4J*fTP#9CxS0%pyD{E&xqk9;{qJwrBJu}*&6`2u*#|$=W=rT=3M$iTd|}#d z;MIO;WYWZv?gW_SDT1%Y%a_tN;F^T*%Sf>|)P6#*!!zs?CcwL_GaME>=I zGY2}Lic0pHz`lgfSGl}yPP)7}0b+KaaHuP`yWfx@9!O@Hv4PCPkjrEDVc1Q-@vHwi zRB1Fbmuxx-l3+F|Zyd!Nuo-WB3xaA^^+jb?vM)f@+0S+l52+tdw|dDbCb&8!N}7ea z6Gc(_+)#h~NsH%MeS9K)_P)HH9_0F>bBbk`*#~>+jBx4NZkg%TEChdo#{XGX*tpiC zJuYb`Dn?9O{wwv6cSUwuXILX2;+-?)B_-|qb|>(AIkfB|?Z&#(vE|*!Ft!;thWI%9 zBRCbC;vl(Y4mfC64NeEX@Suxtj*44B?_R%Ec&r@nDiiW~8h>mmsMA4{XWpQy9EbB8 z%emrk^>{ z`Yvy)dKHw6Uwo6bSuHncG%`j$J?8fD(TmDEx=3G{)2X1q%txa!M19Ifb7 zwW;w!rS=dFQ2IQ>K}>cUy;G~sUOfBGkOWyQD*v&+p#Z)8j@?H%d~bMT6VFQb9uH(t z&rmVEUU4I9P(8(Pg)iik?3kx_XH{37o>+w$xJ-G5P8q8@C;X}!J+E8(q%X>QSx9_x zCw>dXl`a3a_!~Oo+MR0S180bm8kWzv?7FbfA53WH@x_;&H_Ijzg}owmwk4y{tBAXm9BF5L3DoM;oIvWdCx#Isu~oWFb-ARQJaZ6E!&L3Z2~XVi4Ok8l{O#7(nLHLZ}dup)2F&bx1S!9`f#)Fr({ zm=Ifxt*!8D#4AfqDS3py#{>Fa%OlZlBX#pSgg?xa7pyq_%K2iF%-ZgbXK)PKf6Dl) zwExOrt?G080!#dXS@@=u!*n8e7bn>SzmLBqF@#@RPvE=&cwg~>+KFJA3l-n~7GyS`iCEJIR_$O!6dl%yWX z{SzWLxtXw?>e)pF@ea(r=j20)Qb9g#GkN6_y{OP!k1T6MRgdT$hC3~HKtew(zy?r) zYB@lG2gNcip03f2+0L^giN1F{N{QW$Wwy&iXN(n8D%sc5UQ%J=ikeaGfqpwykk$$5 zJ~{0QnTTqx4=#0ht#Tl3@7euwbxvqouoVUT6mv>Ux^LN$u=)^dzWbTfz4dh*E*LK| zn}yps>UQz)^HJ(GLEyz3t+16>Nk4Xv3Ob13@oM6Mq+iDt zYS2-zBiyq#kd@!$_kN3a`FGZjL=YKIKltJzwM!kxj=*q}?sXiFdv7-;m2!d-iQMw2 z!qp;UeZ<4}<625Th{ht9Fop4@e~a@@%a@Jf}8p?}8B`eYIF_(Un2s*!ftPE=#0 z?fzOn*X>bZUF!2Nfs8SFtl5qNk>MN}qTH34TTyG&n@+Ol*>zI{E~XtSDIO&Ok2SK~ zyL_Et`xV<@%5n9vMIX|GTa3~7uGsAM73d<+A{NdK<=Jm}9(WZ`G&R$ELQxwb#pdom z|4br(f3*BrVahq<6Zquf_PQjZMYXs|hQLWoBWsz)KeAg`_@zJH-kgL;ggiKk(dg1W zNFr8uF-1)Bn+Z0I8;LZFM0$=6cnnw0>v&x}0MkaNV*99^(<+bHIZ_gSwj;^x1)dGX z3zy{TB_-V&g^R#2U7jY~p2pw9L#Ur>mG!9Vy}|eG-fj2&{GCUV=+q-3 z_rCb;^9E%q2=R_;Q?%J#g-9E#nM2?$&c5vHkm!vYD>Bf{NbXZphXm?)j6NPOzgIiT_DaN6A;R77?ME5K z*UzB74v9>l8AWo%K+Uk9!(9izZ5+dUExbzJZ>>Z!2E18iyv#w3`3EJ)8TY z$fz_6>bZPG_^33gZZp^5hWGwe$%68W`MVDb=Q(ScS!64(i6SX4%F)yJXCoif>lsuU zITiiSaWZqY>a@KTEF5r_sUZC`3R*`I?mUWC-nH%w&|Zfrjoptp!>`aW_7oW-$0z*d z8HRfpizI2rfJR$yldv#Mqz&`+kT{a)et~Z>yTb!rK9MqR(Ee~>dSrfyT zr6a0SO_ESM*13J{NV+D?8)*avy0|NH(T%ey>%r_Xfppgc>}ix)LfQTIf~z7R1jz4E ze*Wpx3)DxYs$|jx?ou!ylOHROw$(bhJ&7RAJa*d`$OC&M?2F=>JcCD zGRD@tXecz@A{|Qk#RU!ypenwHI-gtlzFWr0>&`DH@#A}O6X|~JX4YmiFydVM^d90+ zo-ej_z((>QdWv3|jk~!+Mf}^KT+<75&O{eMp#4kVh<70Oue}JsW10Em%2t+w$%ejh zaOm79VX|c4K~5O!-I(7y)rf^Xmmxk4>-=7wLVBVpJ3sJ_ zPom@tD;lNZ=AbVuklCp~LdT5lG>*}SuTkO%6g~nyv57hN?hmtly?yq|ia7VHs^nP* z57j3P0aF$0(uliOyk+u;rb{ws&Dxd)W50>)A)>W+0=*Oky~m z`Oz&HZ;H`}73f@!Y8|Tm_I>ei~Mx~wcp=Ln!#Nu<695n*&*Qz<(BNIEnKbk8qsr{qWz zlPGHj9=$e9nOk`zV;5KqFrFCJPt(2M?pY;`lqZc}W!noayY-&(LTXN)g5%YNn6$~P zLe4~7*mUC|6~2Sta*Q>umjEKl!0{7Y9K32ITo93aGu%l2q67%t&Xn1CNzhxd^(X9{ z$>Pj|f>ma(tJ)OZP)REMYeIc;928hS3MP^6LIHjcuM-j~<{t!xF=mq_Srr8iF}WVd zPC^AQFrj$M{pr`f;A+D~utKxM&B$sM*uo7TR9|&M=y!cUZT0J8Ee--#&!YW)jwOZ0 z44Af5?9@nkHW!1x7$Ry|C4B!T^6+K{d7!MwsUz+?k@VKx`&Y7|L6yDGVZ$%1@g$Ze z{i@#&_+*u9VD0P6#U=Ab_!^0l%W$*lbGYWyAunWOjy4s(GuVgjfnqU@o5y7{HPbXg z%RI>UXS?{G41-8@EtF${bCY5v?-p9ys(?K)Jgvz8+5-Y@Qv?@b2KADEg&hueU0^7n9fBUigeZc{?Nd$4_IQ8L!E9-_DjFVM(BHJA>MG? z-o-5$jW4Py)~9s@95iurNK9hwnAN7poI{Hpt+MkInn*W z5p(l9YK$9c^G(n9&|ev%rc2%EeK-m=CK5q5r{h&4Zf$Nu2Z@z3V5|{l%cHQBTGt2V zOLj>gdh`!^`!Ou>W46iw`?AN4!ck2ZS0G%Geq~Sj&}@I@#^Qv|SHG~I9u-|b_P|*a zthEaSLEiz{E^dxwG#X7SJ-5*LvsYt$XXJ*j4Q;1`;&FqGgkDxB-FaL@w9it7gdx{+K4P*N2H#$^w9P9{dv$4hL)6 zGmfyR(Hs{ub@Aw@9S6^Q0UC&SWeXge%U~%jA{$$OLx(32nAb7>?}h2SbU$r8UwTIt zYcgCZ#dOdjswgOESfKn!V}p;8r@pvGft*xW@`;{HnVM!*xZA^PavAUWz&4DqI590{ zNjZ%yGc~xIm2(`R=qx57Pw6yu7qNV-fauu_&`38B0HOCNmBzleF=6_yD4}&n-uJJd zg6uUg-k21(++SO?59?t~tQ*z(f7KL``h#iJ^bM#LFnq#PMZmHX|?#X}-9MzG5H*3Ln0TxGF3v1T1%?x~HX z=L{b}Uz6l?lXs zOwz&-vzm9#G>oVQ?MvWxGx}I~XoZD%nnn)hVTk9S>xW*xr8T52`qh<#xb3$EmdnAQ1gG?s>LSvH z_9i?^@RiYd%iAHIX$?0syo(s%L`48ul!A$r%qwnT9e!Ewc!S_7Lh(p-hS=WRKfDnG zA{DcZPGbSceFZ@ApFmqL)3yNN)! z^k}PXn>$^!PO6hH2}dB043<9Ctq+W)Sc#b>s)nYGmWDdXc2sX&7@0b2Jr2CH;P32Q zzyjv{DBvQBJza{Z{eqE;jm;`Z0deRe1s2`?=xo(Vyn8Apo>BPv65)|7kbB=B*&Tw+=w-#x?E zubKA`I5{{ZndvAgRl|#5yW!<6jDBF#d*NxNM!biHVPN!4x#8??`|(2baSdPcK~D~g zEGh%y>=ERYk!wGw>^@MzrKr%V<|bp;nB!VgEyQS3dZ=RiZbVU&=V6koY0?iVARJ63 z_X32*#LWdX?$PIJH{%R2tv>p}HWI_a>J@yzHNy)%afzrVzB~)9Lo7)w_(e0R!+X)d zS!YO3ts5xquBs}_W|5`CB}q4TJ0w_T_-Ow|Jx}uGRusb9X!xk6F$_5M^jQouR$^XTUo7Ra?!9LC zMAsOe}OyqRnEVmE7aT?hIqRCzB0jTD+sM`dPh#Ln(2`T-2(Z&x(+PQF@>DO_KrR+0mZHFHHIr1YEDghZozR)F zWpzD!sx$&^8~bg$;-bISB=$o6KM?qxlfGZ;7fBjx&| z)beyXIpjWrysY{~?z5;%bu$^OIBscN6%Cf@P65?@@x0x|=7Hr^XyxcZ|JnIdl9a8; z=|~U4>LX)akt~0@VrnM1al0xC;$$sm6L|0ZR9Xp@%?qg`n3PE^K&5MsBnvhjbUX71 z+j;b27;>T_3u4iKf-Khs>Y;ly7uiogO2Ixd(6qA% z)VI;jNIM2l9)tFq!`0_RwJ3ztXYg!X)LZw&x787Rkb`6Ckh)NF9owb5EmfdH0({`& zbtaba9yXs`Sx4oOLh!ev4jI>WXO~7yf^|bnvQ?>*CNW2Gb0q>bZ*c`MigL^5gU)Ix z%O^U)?c2zGNBjd>y&kq*5XNT~2`sg9-{c1H^FPUI5_VKMNrQQOzOz3idp6K29Oo*P!u3p{y zHdf2m=#a4;JI`5v{^c&)Q-m|&sP_im_w(7hZO%$k<5!ZYs(x&F2ST{sHEci3HD2#x zVvvFV+zX`-?;0CL*eu5K)gV-CzU^xSF4Eo)4eW{VXn()0J$XbQ=YC`r`XaqXp7*8u zyh{JZ@_`gB7QN(mfBe;K=fbF(>~y)cdKI>q+Lh5O)w{)3fvSYLvHvGLDX){ueRyR#DM*?B98Hv<%!nwkM8eRNEua8~e{9!nsC zZT~1bI@;%8?(28kekwY;*^Tp7Gb5u1f1lc)VL>jjDY?nfhS`;_w9qeJa=qhc`cG(! z3qVQ?S#U|9gFav|nFJx0|3StxckdSS zc){vJ*?`T)R_gpv>lQ1A&#+X(7a@UWd;8<5;)~jR(*CQB0RgH+{d7sM_ozQhR-e1p z<$PRoM}K_4&Ta+u=AC;YpBBWTR40dJ#gou3l5cYY#}0zlRj<$JH>c1z6;;F+wX!<| z%dNh)8*`R3!v*I#5f+(Fi%)VsP%oQwuNnGF9%Fr{5%t>mQJm0ZD}7D#tqV@9F4d;c z`bQpI2Z;k3C^C+rZ&0=yxG8No|IF7?ldKuuDBpo`e-6otkaws~-%nSaAo(VlK-lp8 z4Hv}x<{#SCTo^+gFbqM4ewvH0s>vH&D%zfx$Wmk_9q9*V>_|unCS!Ve7@c)L(V`;# zFzYt-wDAi_Ap#2_V@&~$xz;fAmg!ykr-66j=MOEx7n6l@UDT^k$$IihGN^Xd^|qkn z;yaFzKQB?-yk+uPg! znKA(B>FFs21fX36dwP5K+XckLrfRGj+}*5dPHMNU(#Y-zu$}pZON}Qrbtt{o`a=_F zKY@(4d^&Edl#S&<16?lbOTrl18q4iBON%~`9vZCxU&=g(i}@MHY{PwC(p?q8_;2D0 zBM+F$sF;(D(jQui+E2v>rw#tTb>YsV&XW09Cb_tEAO9kWP$hiGdku9jtYANpRKyTR zhSo1AyZcB$>U9+4o&UzWFw4ZW)=CXZ-)n5KIebthoB@Kmz+Z6bYKTHt5r z8E>CmZ%M;;Rt90)v;NKkIW5mOM4!%b<&T8uC-7bm%&Q@4td#A031gPK-BzI~ofulv z8Up&)HhUpu4%DM~iK9EcBlppQA;e{1o2gs?mv0R}ZBzZB@{a9iJF)QHnPeQgen`|C ziPI*pyyctLLi9TGJsX)IcGsM392A5`!#a2a3(LFvB1^QmYr+8s#dk>{1Q&ly^cO#YA=(dAJB;L1)C-neUGPd*sQunR=RO{jeKJ( zuZ27XCPV^L>U;gJ#;vA|HBBWsd9<^~_^OgQMqlACCub}K<~MuuKc{(_QX}#w@{L!M z?Z}2DZ#+!=Q&4H9!d=hiqp8Hps&H*2YC_D6*8dsDhx(dGOC#Hhr79^hF)ppD`G+_A zP5jPGB_X&~c#jtY?$Na^XO+L^%`9N(JJ#vO-gkTN0zX>f%TXj|T^Y~fN|lMqgBi zMTdr^;+0;kO-vq-M8@<)s3>gY-GLj{Q*Rae!0 z;!$w-5!TuE-ed{+W`Dv?H4OP0&_#FS1Ch^MXQ)C=`#Iy7>?z5`N>I(qoR^CG!E8}|rN5x_ zX3RB{qE3x5yHjjWny1YqvGiJ0}QjV0*cy8)lr$P^A_AIuv#P~OWN zwE?ZAAJWS-BJmv^9iP^8T=STknv$@{rafB;i0nikddQy7*|LPnV~)|-%M>)%7>f|d zDU!Q!3L?*Yr_Ok?6Lhtw7?cD@>$Qc&=bZ08+J7K=Y4u)<$2r-wK2ASI+6@2Ufg0R` z9L_CS+302t3Z#xZqdZ#>PGNz>woF**jF*Jci3{p+Tl0RmC(z@PG#ltRe`f~;hq=>H z$QU?}+_f-UEVfZDW)rWi=?~14nJGlI6ijtkz8=xXnh=CC6<+5{;uB?8mStU3R6T*p zOYd`s8{%7xSs!_@Bfb)P_LJ|u@$Hkkyri9V&<%K{M^<@Tu`t%AK2#vh&OxJpGk<3v zSsfc>++!CS1*9Ybm#D3x*8NNOXKyRkZx-C7G}46!>)p<&I~is$!$djvINrA6AS^fi zUEtYY)6xb2XJT#*Wzp)RRIx*HDLN+G3w#+Ix&2IF9lJc)T%P%9T(TqSOB;CfxcQ9I z*HkB2T7|HROA){MI7G6;GF}?>=h#sbn~0qs(;BJ!pp5xdUI=J+bAC5f>FJP2gr%_& zj4Y72xEW@PBWGn-&iNfSd_fr(mvWbOF>E6Odm>^JmZ5L)Di14TK#2U8<9LZ1os=-p zN5&&T+w-RMZ7#>Z%W#99cNkFjhWR(2n=yV}#& zd7(l5@$tmCa?cc^tIW#greu$ZuAaKdJ}}HufBiDLd4UQix>=;p!b;TAa|*iK5Vjsy zBx|G(N_A(gJQz#;b!(mEt5EZtvr_v5N>TT#q*jpwZi5x{*Hw~(ndTxz)Th>fURu;JRh(d(rGI%kLv1tmdL5BF%SYW_Qbz^@v0i67{(6V=Y5I#aYSb*h( z(_W|Qwp<(4Yujo`Bo>eI9&dO z%d(fP$^^Zgu#Nl-)@g3I$BXf>B=Q0pFefqVK^o5z+ zn6f_T9%Mh)O$E$LoVcZQmXk8ScWD>ZujG128imoWoJ`3fJKA*UsQsQ0&$8saDdhKJ zBSx_JB5jrx8t=^=`H$v%IpwK|U99J<`D#PY+H7Iwz@!Cz=qmV|$HF!{n;JH6Xeh&& zxm?(HbcBp>j>6wf1EMofhZAk}D~c0T2EOt?R34V|7Zt%_0EHPvkKCzk})LceT2pGzPEh`aqRh4RcW;WI>r8e*pA zl%KS;!rb&3(!@kE2%b7Bx#+oWL9MER>XPME-Kb$I@0SNDz&;DP&_lwnANGF#`R=R3 z>LF3l#*2Yned@aC6R74BN)8{ff7;YW%YG}Vh)*97xqvh+OmV&(%6s7464gyGDIba1 zd17JqiYXHFOer4av6v#0B?XZ$Q0al360AbU)TN)Oc^TMq#c~w()C0_(BfJNKZ#_23 zeb?`>S0|is)1Xn6(m@+CyMC;OWY^Ou^dW zgCqSg0KZaF#`940W%uRIlpWJbHO#oFc)?g$xrU47bwmcyqA)wF`pSH<8UdPJ3#*JH?Sen(QQ5~`u~bkNit zl&RH2cR!jge6_GLSRkF3XqJ^%UIbyzT93A`30n7yW?u8~VH%pHuUIbHF>t%4i>6e% zyI~ISRzjNd7c!z1IA^fg5yE9*O7YGqIqrWvyCnMLhQRCyk0sf-D({~Yg3Iph5MEz6 zfI&;4CjUwCK9e9 zR>^ikYw? zv!rEZaDK==#>><6Ij3JOP1eAkpM&PL{#1yKD0N?QYbegLqZkFNk&9Y1+6SwC^ZFL= z!A`kb<#MZvK^mh?MC)WH0K#&@X5JUGIuCWm8}nFUv-V*v(sllQ=q#v-uQrbI9 zqZ*+MYj}Kzd%7bhup8y~_Cwr!O-O%`@#NAOrBCXtz3D7OCYM9t`<(vkD)ft47T5!L zJ#>fGIKU6xA~55g5#()B(%gj74)VdnMsTH>Yfw3WayzPL#bIz1w1iYD&8oxE;6T_Y4W7Y$L1J0TR&VH$Uki?XeYRZw zUJbT($aG5Ki%VS}D)T@1(9S!4=%GJ!b5N5__BoahTa;sQA-!2xo&$ChP{&OVfk{VL zhJ0@Rv*~O#R?ENl?@CjW%nXs9>FPgBsrtnIe~(0(F73lhT40GBqd7V0at<)t^8KIEenI+xPU57!g@bRQqZW^1H5k%)6wi z){AO7;83ea0nm@?Y5XuDO+TI>aqsfs#S}I5vH^^v)4=K=*y~mE& z!hPY_IR8wP*(w&3l>d9C+bd|P3aio>Z~3FKj7Os&H9#R5$uPB1L-r^0GpPYsv?*1v z4KHq~*654*INs6j`QAN|dQ%(_2ZDk2G~oUI<8w)IsN8oZ^OM9IR+VM}4jT765|$P03%5q2Vu~K( z|L_3gl5qG=wO&CikbtLoX=t#V2*5+ug(+s04tLNC2bm0?t8f+fJ;PlR7BvfBsSRIj z(|%unFO8YF@qq*>?cki3nhnJr)?>-pARCQ`>=*2;d+mizSw4SSXrfuYtMu+p=>a_R z@uRZTpoM)G0Md5$WnuM{#KuQzP}Ra=?eblwXfRcv62~cMfzKZFyS`0G!Fb zB<3}i_&vLM5@YLvAp|rbM|+uJf*aZ(4Ileph7rXRwKrpx%Ud5z3LR{@IN=S$~dF|K82!3~un@8dE<0Gp@lTr@5RJ@YcJ%$xBn|WS}Lx zwp9#E%P(J7=~c%;p3y)`$c+~__ortv9tk`zZrYDi8)#EMtO-z>E^qXQQ$hS;QxzkL z;t0#PdkW_pJi=&@ScFw=5Cqpg{4vNl?AnMK;Sn6 zL8wsxmgcBfPWEyp;YL>7@3f(v}=I+i09Q94PbON z9~l|orW8H#X`h3+OYut}l~*z!NW=GBMi~koyD+DsBdRUi5E!45G)dxtaWrc%*x2iuO&7Ipm{C@ib5T z3~sKk4`RLr1mP@y5OL9ohj2NR`kqeP9V1mGJ9M)#2!8TS6$>@**(Im(2k{2qKWz); zKe#gH{PIcT^sY6CLFppr^hh7mH-MSh6!#O0*WNap_=7b0He=i!dg~rysw`qQMo!FD z3S~)daZ7UeFc6gMRL>~kKi{ir{;8i82RJFczWO>r#i#oG)Ak($UWQRdz&3^GLErCnQGdEhgUT@4!VY zB_Ieo4oSP?k1`cma z=ikLl46taB>@URtWi;iLE^sq?Kw%{W(awwjsGa_u7Zx!obMYI;c*U&5s}tB~lQ)c` z*RB#O9W0O_r&rCQn1Nn73qK`9&>cE-m&+l|SDoEPud1Y^9lCvwlwXCe%66!PA^Z2? zRR&9u);JF#H;&1nd37e!B26VuwI0H4UX+zrbQt37NC&$bg*;!fo+T1xf&{>ICSc2Y zBgS}n`t2@i4tI-R695zK*)Cv|mPN&%GRlv>&3-pfwPJO_lffl1T~}=$xr8TjN|*D3 z@Ml~e#p4@Wy3`2tK*}=<897bqz)>`gyhXg z%si9fA4Py~lz20fo$?z@7_g5pRnbxcH;6Yf0XW?6VH$ z(sa`ejV_$CQ?v1m`@4BH!3ltBhs#@C$v^e2eARN=x1U})ux!VSVX>)JJozhE%};+g zu1#mgv>uVgt2OUE2)KXdOmueLviHY>RV_Zn3Es#R_ihQCz%5%)rj2xH1DYL7-P4K5 z^;rNIeW%xfu;Z#U!v_H74J#z&VOyo5+hlAH>PSX+kQ@(O9VHVQb(pKH?11q1^~{c< zP`>>3uYCjQ-*kgBZDvzF1IdAEh+=4g(yZ3hfQ|``;njMpflUF|$Kl1InX;LjpVbMK zT&O>mnHeyk8z99_)%8J-xNzAQSnrJ0T_J#}Gq_d^4$772vps8L1N5jpfY)V<>LiR0 zQ<|+nk9!;T6#c;xkJqQ_#f_1$VB@3Z`84$*Wh$g`zkJAb-&-dB*fKMV6mIts7CH%n zOr_TJ%${*0zq$o4lCeb*C?;~~60qG`1d#mj|FS0gg+3nc{$)X-W&WhqcHgk^Zq9Ed zd&5#jaaQco6|c=N&v|pGv%7^_q)+Yz0==2Qj<}||c#mV%s7%0yl^FMTWfVE^koTI8 zeP6Saw9NZm0WsR**5jibpR$Jl6pavw%5OX@%Yjflyx9jT$d0(vVFixyP;N4N1t6~k z?PELMD2m6A0N4~j%K+sY8|R?cNt;{vsby}npV}9gfr=6C`o@jE*8Z%8st`prI66D0 zWjR;<@BRP*&?#>IcL`tI2aj`M*yTe&K}NFYYixQQIQX0YqAh`**$7FC%=Gh)aU287 z*i&Q_ca0PaD}W-iI^Ci4N#6i&E0FY8u%nKnqI4;yX@5=gJb#wC-rqmv+glu@0E5bB zTZ;Y#M}^d!2wkeBoxP;@Vdrp|`}!+xCx@|*$%Bh zA@asOPmaKFmSOb}9dXwi!$b166=WdxS@!E23oM`e;tS9}Y=$WSwg);$;}6JE`d?mR ziz*>$)pL7!hf8~>beM2m;D)Y!wu^cF)#!x})#Hu4S;>CenC0R|w;)B6IR8biENT|~ zVgjhuhWb9-rQGnH(id(dz&BWby%}W!&|tH2vH^Cfz{?MtBKQ5z+{UrbdU>ZC`?su# z{AHgAJY-qI^}l^&hrZ43w$9w{*kXr9^{{@+tv^)%aZ~+JnSc`V*Z(A7ljZz@!_KOI zlPwsPDUWOW-eVyj9}#Hb2fhZoogA{YR{1Y*yn3=p1hu$ht_+%N0@@%?F7|Ft-FE`3 zC>f9`0luwkr2DHRjKhmR9YuK8;v!mOuzV;bf8H_lBfAnFU=uI|^{9pFr zfBaYJ5R5Z6?2=q~M1KeM4&Z~A8P|1pRoL7xrVP6p6S854>DZpZ1q)URbRogaAH7{? zb6574(Ag^mjfB}*ux#LZ#lNbYA|Lf$Cz7(BO?q&apAz{-sO!b>)9dRNXO1@R3_KUh z*q5R<$fqXf%$1=qq*uwgnGx%%kQaa_?p60-E-uYy#B$@^gK%kxicqO2`e7s?p zgBeydHn+Dt>ldid=Jiz*!+|9FWUMz?P{pLOH3Uw&*O3@hu{!oJawu^d%I3i}Wmt~d zacgb-Jx>5=Vou+GxsNTPdo9yuk;^lH6M&!R8(0rj02M%s!a!t?tIn1uYW{3Y;z9d` zs$>JR$dj_w0xC8hLQPObC2}`1Gb9)s7<5gsI%^Arz!;qD|B41hcb8)nlYA5qVSPR5 z**ui)EjSb|M?4Lv7MW`51dSNX&T#niMZ4>#*MmAELBZ`DnUxCvkB|~j@;%;I z`~1)GA`}Ro;!{F>1%ss@-YqaSFe1_jxxpD7H95A^erOqsgQ(WvonA| z`Qrc46%>!t=t;gLVp3Zfb{<`l_zBcnC>)$`FOR{^*u;q5HdXxao_;{e3RF6l3Peub z!FRD{7XivvW&KCKDY~E9K3=NBpn|ESep<_DTHAYO__%o+h{lzkm7}9OW511sIH^tM)P~b8Y5dx#Vt}b!E8umF|)Is7#La^-^ zOR)1+q^9#u+GVzyQ(8L1YxAd`rKP)^{X&D&!BR_7-zU0LV615E>pmi6$BjEk78m#= zWrF($w797Xm~#DPtK?N-oBQkWpVnJG9}fu`DacjJEuEFwCQ1Qs)FlSWA3kv9taanF zzUd0X9Fex16tfK6<-EJ>R}gvk=M5ei^FZf4+Cw)-c97007_;mDg0qv|?RH@Qd-L^@ zn8hlyXY_fJ>W6eY<*T8mWIv#%I*Wi6df!kkjR4YAkGZ&Fg>8SD2!2XP-~s@9(-klO z<`8QGQO*E8>E(l)Q2}*f5NYj0}y8-XR!T zbUl(38g-gu&%8X7?npx>`n&npuA5Fdqe$8a`T2;db|mA>R{FENIDdja3HdWc&$!d$ z40)deb%&{!iVAp{c^wnj zwa)dkOAS{1XTX-Yz|2d3Z(<9s97{RJ=_G~&I4hfCQ0@vs7)aWB?{-X1OkfO*j1*bO zEJ~LxEt%tyv$)DV5fmI-_nV%c24?)4d06EhAA9}PQ&Cu7yQK-`@;UxhPtim<%jHU8>U8>g(#B zK7DGv`7@q`NrEH{kTt^kd2M_9V)X^iznt@zcX51ZFACHX>ggbRH$$FdN z6n--CVNnqglUi#`47|v2e3pPPh5M_qVAS+W*VT?}GmrMK({;MziZ#PH$H4a}pD&{>m2-5fMF*eEmer|M>Cap1@!DtifFe^YsjJfnsU} zUtMb2Q&O!$=4C*d|8C{4mZpJYUbnqFO?&2HSf?)KD(RVz{QfAd}s`F|X*e}DhK zKBo5MK!C@0CyIzEDJkFB+t;}-OItnD5bFg7Y&8QgXAKaj-&*LnkIqWcyvB*qd;3?O z1c`}V-|b|pySnmm zb8~B_i$u!>ol7zsSXzz(7+%N4Mt)&oVe_Cv=`gazz zwk~9X{t;V)&RW{8b%oDllmnmxKJ#XHVEdVe=R0J}ju1VG>~R_TpxO!sl*l z&&$Dqfm%yJG}EPSmSi_zzqA({-9E&{{k1`^bG6-p?ZLA|u0Srn?37W0p5#}CIPr19 zEKs>r1@C7K{RQa79{{<30`PizF-HnOov;I{YgUI^=P5V04IHA>cD+}Dvb^sh7CZ)E zey7*_HTA$u^8A7VhG*`~TU%Q*w*O~j{`rgnMZ8HzuoN&G@byTBIG<%(8UV5Q`T3!i zhQ=%Y&F9Hyomg62`LQ+z@^`2;8&f%xdJ5)`B)8x;+A%D;ZT zvZ$!YNwDKGA5{l{rub!L&2JC|31T{v4FC%{g*Aqt1NViA=>(>L+@0UX55gL#g&4@v zG6&CbI8|^~Ob6uv2>3YwvwD><-yYP2=UDNwW(K&t;|3`+;wa_}V1Z|BErSll`2_@Y zD@sd`k<=6;6U91AZom-fiB6@$($eSq^YtZ-fIT}*)Djp+cHW2RO#T*UCSeIW5dL4i zU3)x~`5Gs?VG}E>a*0}{PAE;~8f}!0OIY^UlIyxe$Yl*0CQ4!Dn%uY85=#*>uDO&l z>E@5{M-&j05ef6T|{Gc)h|d!P4tzR&l0=J&i`H{45>)o%F7@e&aq?4qdVZ&r*=O>37HrV$T2J?4jkDk2igP*utVc@KUlx36#YEsveh6gksj{p64Noks1X>eCy zB+JdvP!MMqY)dte-6SG%Z-o=_!F2%n@e|xXBXDIoXt+8*UlFuQGAg%|&f*9$+xWXX zs;KG+?W<6yYS5U=hcx=)?5G?^V&_0ZS_6W^53Vv|0U|L^I(RTy*JG+^FOm@eP%T|?? z0&JSQxRLiV>W!unck9qsi!(!ZmUY|V7<5dv%umv#%P?7yo4D}G<@CB4Gg*202;15a zf@qC6zyQ1S6Jp}y`)d<^OBima$zflsAoc7&_!l)bKK{h9W84zT7mB2&Ta1p{Dy7!H zemz4;y(V+2B}v0yX~SmuPg!Y~?tr}swh7@X8XJv6HM_usa8+bx-)KjPdVuO_j58r+ zlB>M=R&10~v;X`vW_jZ}T(~2IGhIIvK3_Z-Fz*2;a_mgh6x@f(NK(Zk2v=0^qQYn4 z*K>{hG8J`1A||7FrYz->9z#DkBO^o6xq0V^!=-6)AN?FvVPiPr!)u|TF4F^VTJYU_ zop3C3Ev+lsN?JW>;o;#$Z&H(I=926voPJ`WPNGj zUa?z;k{d*g&D-)UX@!NP5o(0=Q7Z|OeONJ4!suXHU@K+zOLnJUUt|?U?skSIq{CcaJr>NZYJ=OQTA4P6+KKIKAsA1%{JYwATMvAzOpn;gJ$Y{x$YgY zgngDd+~i9aDn^w~wfwXYeUvj~WPbj9&Soj8yhtex^NvU7qHC$hV>%U+brQ6sq^$&y zS8!%KXrNQlMJBpYgP* zSY8~V!3CUcZEelrVl+gxRY!GTHH$LTT{FjOvv%RI=h{%K&;Zq=pcCGuR#h%vR{=(? zc!p3};U7i#IXBdo|t%NkHfcT*>7@MetN%nl0iFv@Hs9xL-@Khl!lyehn_BaLi zB(LDRKwVW7A#} zgnqP?#_3XzKWgnp-xmb)i^yVxQTzP)y(J&LHXu=5$ak}*vP4a@3?1qs#AcXH!IwCT zo_&$ZQ!_0_JQMSM(bHf^ll_U-<|mgD70#}&!E{EF8hI}oE|?f1`VNB9ny!`Z9950U zXCgay?-tpzg^m!^c5t}Yu}n0^ukK$nU=eA&a!yKDSNFl$k|<=IL^MvkI>~JZetE{H z^j?G|BwoFYmpcRHS{NEg(zS!jy3n4#!gt&eksC16 zbaH8~dZiyd6_0Ugq6(ZKtu;K&9KmIlkPb4=HQYY3$h>>}`0<#VH=kMhcAjXst$}q5 zo_mX7zhXD8CFtPVzlhm!1gXs4-k!*1T^9$pAy!{@Rr&+K=u-X>AoAtjLt5iqmC2e^ zwX}dKe#b{*#x3JAGBW%^LM2i2q1UcWB3sxgr6#NU?gMp6H%ikapjJ|Y!ccoE`0eJ+ zb;PD&u+5}H&YOs#EO<*HYZ)!=upf4=bzENxNUAiJOK;kwg@uVJ+61u*8H}H}rlzL2 z-j|c*^b_~d@|>f8`)!Ae3{MabuONfHb+nykhe<)ACMR+?@R2|l?4s><`nD4K%(LU& zMy{?8SOp*}f7!p^*Y5$+q_C){14jc}_j`MPL9=7vDFnD-JE7H|Qm#5VpwF@Gk}~0< zVgl>AT((7DKUNkB;o&fXq3N_wWMf~jkmjGiT6%eT^%)u9416AImG7M&v3a^5N6W$`B^l%el9?SP`?+@Q+7*UTmU7w2mWw96&pf zfwx{XGz@~=+jACKL=prd-G(}OrD0HRs_L(@MjEW|AUxd*$0H6y^e`~WP*_;V#YDLW zliR^He%GX?pa?-e)iE*I6t~;RvHxYfq?&h_!>a^O49$5i&3le;el{~B+0_XECZGFu zQ|Ux`1WY&}-hV$5_p@eK+AphX`iVkO!x`^nW`-c>NH#TGQhuMffivO)VPL|wDTiH3 z$I3^T@9uADv+`F!#VLQL@G6q%I*&F>-=+#*ckot2FE0`fLJaVU%9%AHu@F@d5Uv(n zdJpdD)*q$O5kV>Wx%c}10hC{ZIrsB=;f-^3Y1+h%-5Q+fobpg&6^xrKTC$AraLORm zAy3;*31gif^>o&H+k`#;v!7v4{3wM(;H8Jx9#89E{rA7n!}z~6N|ukt=5Apc{Iyn$ P3xB#N43Fn&*&Os3o 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 IUcUXm0F0+e1ONa4 literal 0 HcmV?d00001 diff --git a/docs/community/base-reward-function.md b/docs/community/base-reward-function.md new file mode 100644 index 00000000..b071ab7b --- /dev/null +++ b/docs/community/base-reward-function.md @@ -0,0 +1,33 @@ +--- +layout: "default" +title: "BaseSetpointEnergyCarbonRewardFunction" +nav_order: 1 +parent: "Reward Functions" +grand_parent: "Smart Control Project Documentation" +--- + +# BaseSetpointEnergyCarbonRewardFunction + +**Purpose**: Provides a base class for reward functions that consider productivity, energy cost, and carbon emissions. + +## Key Attributes + +- `max_productivity_personhour_usd`: Maximum productivity per person-hour in USD. +- `productivity_midpoint_delta`: Temperature difference from setpoint at which productivity is half of the maximum. +- `productivity_decay_stiffness`: Controls the slope of the productivity decay curve. + +## Key Methods + +- `__init__(...)`: Initializes the reward function with productivity parameters. +- `compute_reward(energy_reward_info)`: Abstract method to compute the reward; to be implemented by subclasses. +- `_sum_zone_productivities(energy_reward_info)`: Calculates cumulative productivity across all zones. +- `_get_zone_productivity_reward(...)`: Computes productivity reward for a single zone based on temperature. +- `_get_delta_time_sec(energy_reward_info)`: Calculates the time interval in seconds. +- `_sum_electricity_energy_rate(energy_reward_info)`: Sums up electrical energy rates from devices. +- `_sum_natural_gas_energy_rate(energy_reward_info)`: Sums up natural gas energy rates from devices. + +--- + +[Back to Reward Functions](reward-functions.md) + +[Back to Home](../index.md) diff --git a/docs/community/best-practices.md b/docs/community/best-practices.md new file mode 100644 index 00000000..62399b11 --- /dev/null +++ b/docs/community/best-practices.md @@ -0,0 +1,42 @@ +--- +layout: "default" +title: "Best Practices" +nav_order: 10 +parent: "Smart Control Project Documentation" +--- + +# Best Practices + +- **Modular Design**: + + - Keep modules and classes focused on single responsibilities. + - Facilitate reuse and maintainability. + +- **Error Handling**: + + - Use try-except blocks where exceptions might occur. + - Provide meaningful error messages and log exceptions. + +- **Logging**: + + - Use the `logging` module instead of print statements. + - Set appropriate logging levels (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`). + +- **Documentation**: + + - Keep documentation up to date with code changes. + - Use comments to explain complex logic or decisions. + +- **Performance Optimization**: + + - Profile code to identify bottlenecks. + - Optimize algorithms and data structures where necessary. + +- **Configuration Management**: + + - Use configuration files (e.g., Gin) to manage parameters. + - Avoid hardcoding values in the codebase. + +--- + +[Back to Home](../index.md) diff --git a/docs/community/building-simulation.md b/docs/community/building-simulation.md new file mode 100644 index 00000000..0397e324 --- /dev/null +++ b/docs/community/building-simulation.md @@ -0,0 +1,36 @@ +--- +layout: "default" +title: "Building Simulation" +nav_order: 1 +parent: "Simulation Components" +grand_parent: "Smart Control Project Documentation" +--- + +# Building Simulation + +**Purpose**: Represents the thermal and physical properties of the building, simulating how it responds to HVAC inputs and environmental conditions. + +## Key Classes and Components + +- **`FloorPlanBasedBuilding`**: + + - Simulates the building's structure based on a floor plan and zone mappings. + + - **Attributes**: + + - `cv_size_cm`: Control volume size in centimeters. + - `floor_height_cm`: Height of each floor. + - `initial_temp`: Initial uniform interior temperature. + - `inside_air_properties`: Thermal properties of the air inside the building. + - `inside_wall_properties`: Thermal properties of the interior walls. + - `building_exterior_properties`: Thermal properties of the exterior building. + - `floor_plan_filepath`: Path to the floor plan file. + - `zone_map_filepath`: Path to the zone mapping file. + - `convection_simulator`: Simulates heat convection within the building. + - `reset_temp_values`: Function to reset temperature values. + +--- + +[Back to Simulation Components](simulation-components.md) + +[Back to Home](../index.md) diff --git a/docs/community/configuration.md b/docs/community/configuration.md new file mode 100644 index 00000000..c5da8c71 --- /dev/null +++ b/docs/community/configuration.md @@ -0,0 +1,124 @@ +--- +layout: "default" +title: "Configuration" +nav_order: 6 +parent: "Smart Control Project Documentation" +--- + +# Configuration + +The project uses Gin configuration files (`*.gin`) to manage simulation settings, reward function parameters, and environment configurations. + +## 1. Gin Configuration Files + +Gin is a lightweight configuration framework for Python that allows parameter bindings via configuration files or command-line arguments. + +### Structure of Gin Files + +- **Parameter Definitions**: Define values for various parameters used throughout the simulation. +- **Function and Class Bindings**: Bind parameters to specific functions and classes. +- **References**: Use `@` to reference functions or classes, and `%` to reference parameters. + +### Example from a Gin File + +To illustrate, here is an example of a Gin configuration: + +``` +# paths +controller_reader.ProtoReader.input_dir = @get_histogram_path() +floor_plan_filepath = @get_zone_path() +zone_map_filepath = @get_zone_path() +metrics_path = @get_metrics_path() +``` + +## 2. Key Configuration Parameters + +### Simulation Parameters + +- **Weather Conditions**: + - `convection_coefficient`: Coefficient for heat convection between the building and the environment. + - `ambient_high_temp`, `ambient_low_temp`: High and low ambient temperatures for sinusoidal temperature variation. + +- **Building Properties**: + - `control_volume_cm`: Size of the control volume in centimeters. + - `floor_height_cm`: Height of each floor. + - `initial_temp`: Initial temperature inside the building. + - `exterior_cv_conductivity`, `exterior_cv_density`, `exterior_cv_heat_capacity`: Thermal properties of the exterior building. + - `interior_wall_cv_conductivity`, `interior_wall_cv_density`, `interior_wall_cv_heat_capacity`: Thermal properties of the interior walls. + - `interior_cv_conductivity`, `interior_cv_density`, `interior_cv_heat_capacity`: Thermal properties of the interior air. + +- **HVAC Settings**: + - `water_pump_differential_head`, `water_pump_efficiency`: Parameters for the water pump. + - `reheat_water_setpoint`: Setpoint temperature for reheating water. + - `boiler_heating_rate`, `boiler_cooling_rate`: Heating and cooling rates for the boiler. + - `fan_differential_pressure`, `fan_efficiency`: Parameters for the HVAC fan. + - `air_handler_heating_setpoint`, `air_handler_cooling_setpoint`: Temperature setpoints for the air handler. + - `air_handler_recirculation_ratio`: Recirculation ratio for the air handler. + - `vav_max_air_flowrate`, `vav_reheat_water_flowrate`: Maximum flow rates for VAV boxes. + +- **Occupancy Model**: + - `morning_start_hour`, `evening_start_hour`: Hours defining the occupancy schedule. + - `heating_setpoint_day`, `cooling_setpoint_day`: Setpoints during the day. + - `heating_setpoint_night`, `cooling_setpoint_night`: Setpoints during the night. + - `work_occupancy`, `nonwork_occupancy`: Occupancy levels during work and non-work hours. + - `earliest_expected_arrival_hour`, `latest_expected_arrival_hour`: Arrival times. + - `earliest_expected_departure_hour`, `latest_expected_departure_hour`: Departure times. + +- **Time Settings**: + - `time_step_sec`: Simulation time step in seconds. + - `start_timestamp`: Start time of the simulation. + - `time_zone`: Time zone for the simulation. + +### Reward Function Parameters + +- `max_productivity_personhour_usd`, `min_productivity_personhour_usd`: Productivity per person-hour. +- `productivity_midpoint_delta`, `productivity_decay_stiffness`: Parameters for productivity decay curve. +- `max_electricity_rate`, `max_natural_gas_rate`: Maximum energy rates for normalization. +- `productivity_weight`, `energy_cost_weight`, `carbon_emission_weight`: Weights for reward components. + +### Action Normalization Parameters + +- **Supply Water Setpoint**: + - `min_normalized_value`, `max_normalized_value`: Normalized action value range. + - `min_native_value`, `max_native_value`: Native action value range (e.g., temperature in Kelvin). + +- **Supply Air Heating Temperature Setpoint**: + - Similar normalization parameters as above. + +### Observation Normalization Parameters + +- **Per-Measurement Normalizers**: + - For each measurement (e.g., `building_air_static_pressure_sensor`, `cooling_percentage_command`), define: + - `field_id`: Identifier for the field. + - `sample_mean`: Mean value used for normalization. + - `sample_variance`: Variance used for normalization. + +### Environment Parameters + +- `discount_factor`: Discount factor for future rewards. +- `num_days_in_episode`: Number of days in an episode. +- `metrics_reporting_interval`: Interval for reporting metrics. +- `label`: Label for the simulation or environment. +- `num_hod_features`, `num_dow_features`: Number of hour-of-day and day-of-week features. + +### Bindings and References + +Bind classes and functions to configured parameters, for example: + +``` +sim_building/TFSimulator: + building = @sim/FloorPlanBasedBuilding() + hvac = @sim/FloorPlanBasedHvac() + weather_controller = %weather_controller + time_step_sec = %time_step_sec + convergence_threshold = %convergence_threshold + iteration_limit = %iteration_limit + iteration_warning = %iteration_warning + start_timestamp = @sim/to_timestamp() +``` + +Reference parameters using `%` and functions or classes using `@`. + +--- + +[Back to Home](../index.md) diff --git a/docs/community/ddpg.md b/docs/community/ddpg.md new file mode 100644 index 00000000..20ed057d --- /dev/null +++ b/docs/community/ddpg.md @@ -0,0 +1,24 @@ +--- +layout: "default" +title: "Deep Deterministic Policy Gradient" +nav_order: 3 +parent: "Learning Algorithms" +grand_parent: "Smart Control Project Documentation" +--- + +# Deep Deterministic Policy Gradient (DDPG) +Implementation of this algorithm can be found in the `DDPG_Demo.ipynb` notebook. + +--- + +Deep Deterministic Policy Gradient (DDPG) is a model-free reinforcement learning algorithm designed for continuous action spaces. It combines the actor-critic framework with deterministic policy gradients. Key features of DDPG include: + +- **Actor-Critic Architecture**: Utilizes an actor network to select actions and a critic network to evaluate the Q-values of state-action pairs. +- **Off-Policy Learning**: Learns using a replay buffer to sample past experiences, improving stability and efficiency. +- **Target Networks**: Employs slowly updated target networks to stabilize training. +- **Exploration**: Uses noise (e.g., Ornstein-Uhlenbeck process) for exploration in continuous spaces. + + +[Back to Learning Algorithms](learning-algorithms.md) + +[Back to Home](../index.md) \ No newline at end of file diff --git a/docs/community/electricity-energy-cost.md b/docs/community/electricity-energy-cost.md new file mode 100644 index 00000000..351a3e7a --- /dev/null +++ b/docs/community/electricity-energy-cost.md @@ -0,0 +1,35 @@ +--- +layout: "default" +title: "ElectricityEnergyCost" +nav_order: 4 +parent: "Reward Functions" +grand_parent: "Smart Control Project Documentation" +--- + +# ElectricityEnergyCost + +**Purpose**: Models the cost and carbon emissions associated with electricity consumption. + +## Key Attributes + +- `weekday_energy_prices`: Energy prices for weekdays by hour. +- `weekend_energy_prices`: Energy prices for weekends by hour. +- `carbon_emission_rates`: Carbon emission rates by hour. + +## Key Methods + +- `__init__(...)`: Initializes the energy cost model with price and emission schedules. +- `cost(start_time, end_time, energy_rate)`: Calculates the cost of electricity consumed over a time interval. +- `carbon(start_time, end_time, energy_rate)`: Calculates the carbon emissions from electricity consumption over a time interval. + +## Calculation Logic + +- Determines the appropriate energy price and carbon emission rate based on the time and day. +- Converts energy rates to costs and emissions using provided schedules. +- Supports variable pricing and emission factors throughout the day. + +--- + +[Back to Reward Functions](reward-functions.md) + +[Back to Home](../index.md) diff --git a/docs/community/environment.md b/docs/community/environment.md new file mode 100644 index 00000000..5149e414 --- /dev/null +++ b/docs/community/environment.md @@ -0,0 +1,139 @@ +--- +layout: "default" +title: "Environment Module" +nav_order: 2 +parent: "Smart Control Project Documentation" +--- + +# Environment Module + +The `environment` module provides the reinforcement learning environment where the agent interacts with the building simulation to control HVAC systems. + +## `environment/environment.py` + +**Purpose**: Implements a controllable building RL environment compatible with TF-Agents, allowing agents to control various setpoints with the goal of making the HVAC system more efficient. + +### Key Classes and Functions + +- **`Environment`** (inherits from `py_environment.PyEnvironment`): + + - **Attributes**: + + - **Building and Simulation Components**: + + - `_building`: Instance of `BaseBuilding`, representing the simulated building environment. + - `_time_zone`: Time zone of the building/environment. + - `_start_timestamp` and `_end_timestamp`: Start and end times of the episode. + - `_step_interval`: Time interval between environment steps. + - `_num_timesteps_in_episode`: Number of timesteps in an episode. + - `_observation_request`: Template for requesting observations from the building. + + - **Agent Interaction Components**: + + - `_action_spec`: Specification of the actions that can be taken. + - `_observation_spec`: Specification of the observations. + - `_action_normalizers`: Mapping from action names to their normalizers. + - `_action_names`: List of action field names. + - `_field_names`: List of observation field names. + - `_observation_normalizer`: Normalizes observations received from the building. + - `_default_policy_values`: Default actions in the policy. + + - **Reward and Metrics**: + + - `_reward_function`: Instance of `BaseRewardFunction` used to compute rewards. + - `_discount_factor`: Discount factor for future rewards. + - `_metrics`: Stores metrics for analysis and visualization. + - `_metrics_reporting_interval`: Interval for reporting metrics. + - `_summary_writer`: Writes summary data for visualization tools like TensorBoard. + + - **Episode and Step Tracking**: + + - `_episode_ended`: Boolean flag indicating if the episode has ended. + - `_step_count`: Number of steps taken in the current episode. + - `_global_step_count`: Total number of steps taken across episodes. + - `_episode_count`: Number of episodes completed. + - `_episode_cumulative_reward`: Cumulative reward for the current episode. + + - **Methods**: + + - `__init__(...)`: Initializes the environment with the specified parameters and configurations. + + - **Environment Lifecycle Methods**: + + - `_reset()`: Resets the environment to its initial state, preparing for a new episode. + - `_step(action)`: Executes one time step in the environment given an action from the agent. + - `_has_episode_ended(last_timestamp)`: Checks if the episode has ended based on time or steps. + + - **Agent Interaction Methods**: + + - `action_spec()`: Returns the specification of the actions that can be taken. + - `observation_spec()`: Returns the specification of the observations. + - `_get_observation()`: Retrieves and processes observations from the building, including normalizing and handling missing data. + - `_create_action_request(action_array)`: Converts normalized agent actions into native action values for the building. + + - **Reward Calculation Methods**: + + - `_get_reward()`: Computes the reward for the last action taken based on the reward function. + - `_write_summary_reward_info_metrics(reward_info)`: Writes reward input metrics into summary logs. + - `_write_summary_reward_response_metrics(reward_response)`: Writes reward output metrics into summary logs. + - `_commit_reward_metrics()`: Aggregates and writes reward metrics, and resets accumulators. + + - **Utility Methods**: + + - `_get_action_spec_and_normalizers(...)`: Defines the action space and normalizers based on the building devices and action configurations. + - `_get_observation_spec(...)`: Defines the observation space based on the building devices and observation configurations. + - `_format_action(action, action_names)`: Reformat actions if necessary (extension point for subclasses). + - `render(mode)`: (Not implemented) Intended for rendering the environment state. + + - **Properties**: + + - `steps_per_episode`: Number of steps in an episode. + - `start_timestamp`: Start time of the episode. + - `end_timestamp`: End time of the episode. + - `default_policy_values`: Default actions in the policy. + - `label`: Label for the environment or episode. + - `current_simulation_timestamp`: Current simulation time. + +## Environment Workflow + +1. **Initialization**: + + - The environment is initialized with specified parameters, including the building simulation, reward function, observation normalizer, and action configurations. + - Action and observation specifications are set up based on devices and configurations, involving action normalizers and mappings. + - Auxiliary features such as time of day and day of week are prepared. + +2. **Resetting the Environment**: + + - The `_reset()` method resets the building simulation and environment metrics. + - Episode counters and timestamps are initialized. + - The initial observation is generated by calling `_get_observation()`. + +3. **Stepping through the Environment**: + + - **Action Application**: + + - The `_step(action)` method processes the action from the agent. + - Actions are normalized and converted into native values using `_create_action_request(action_array)`. + - The action request is sent to the building simulation via `self.building.request_action(action_request)`. + - The environment handles action responses, including logging and handling rejections. + + - **Observation Retrieval**: + + - After the action is applied, `_get_observation()` retrieves observations from the building. + - Observations are normalized using the observation normalizer. + - Time features (hour of day, day of week) and occupancy features are added to the observation. + - Missing or invalid observations are handled using past data. + + - **Reward Calculation**: + + - The reward is computed using `_get_reward()`, which invokes the reward function's `compute_reward()` method. + - Reward metrics are logged and written to summary writers if configured. + + - **Episode Termination**: + + - The environment checks if the episode has ended using `_has_episode_ended(last_timestamp)`. + - If the episode has ended, a terminal time step is returned, and the environment is reset for the next episode. + +--- + +[Back to Home](../index.md) diff --git a/docs/community/glossary.md b/docs/community/glossary.md new file mode 100644 index 00000000..1a837fc0 --- /dev/null +++ b/docs/community/glossary.md @@ -0,0 +1,24 @@ +--- +layout: "default" +title: "Glossary" +nav_order: 12 +parent: "Smart Control Project Documentation" +--- + +# Glossary + +- **HVAC**: Heating, Ventilation, and Air Conditioning systems. +- **RL**: Reinforcement Learning. +- **TF-Agents**: A library for reinforcement learning in TensorFlow. +- **Setpoint**: The desired temperature or condition that a control system aims to maintain. +- **Regret Function**: A type of reward function that measures the difference between the actual performance and the optimal performance. +- **Gin Configuration**: A lightweight configuration framework for Python. +- **Productivity Decay Curve**: A function describing how productivity decreases as conditions deviate from optimal setpoints. +- **Energy Cost Models**: Models that calculate the cost and carbon emissions associated with energy consumption. +- **Normalization**: The process of scaling data to a standard range or distribution. +- **VAV**: Variable Air Volume systems used in HVAC to control the amount of air flow to different areas. +- **Control Volume**: A defined region in space through which fluid may flow in and out, used in simulations to model physical systems. + +--- + +[Back to Home](../index.md) diff --git a/docs/community/hvac-systems.md b/docs/community/hvac-systems.md new file mode 100644 index 00000000..3984e32d --- /dev/null +++ b/docs/community/hvac-systems.md @@ -0,0 +1,57 @@ +--- +layout: "default" +title: "HVAC Systems" +nav_order: 2 +parent: "Simulation Components" +grand_parent: "Smart Control Project Documentation" +--- + +# HVAC Systems + +**Purpose**: Models the heating, ventilation, and air conditioning systems of the building, including air handlers, boilers, and variable air volume (VAV) boxes. + +## Key Classes and Components + +- **`AirHandler`**: + + - Controls the air flow and temperature in the building. + + - **Attributes**: + + - `recirculation`: Percentage of fresh air in the recirculation. + - `heating_air_temp_setpoint`: Setpoint for heating air temperature. + - `cooling_air_temp_setpoint`: Setpoint for cooling air temperature. + - `fan_differential_pressure`: Pressure difference across the fan. + - `fan_efficiency`: Efficiency of the fan. + - `max_air_flow_rate`: Maximum air flow rate. + - `sim_weather_controller`: Weather controller for ambient conditions. + +- **`Boiler`**: + + - Provides heating by controlling water temperature. + + - **Attributes**: + + - `reheat_water_setpoint`: Setpoint for reheat water temperature. + - `water_pump_differential_head`: Pressure difference across the water pump. + - `water_pump_efficiency`: Efficiency of the water pump. + - `heating_rate`: Rate at which the boiler can increase temperature. + - `cooling_rate`: Rate at which the boiler can decrease temperature. + +- **`FloorPlanBasedHvac`**: + + - Integrates the HVAC components into the building simulation. + + - **Attributes**: + + - `air_handler`: Instance of `AirHandler`. + - `boiler`: Instance of `Boiler`. + - `schedule`: Setpoint schedule for HVAC operation. + - `vav_max_air_flow_rate`: Maximum air flow rate for VAV boxes. + - `vav_reheat_max_water_flow_rate`: Maximum water flow rate for reheating. + +--- + +[Back to Simulation Components](simulation-components.md) + +[Back to Home](../index.md) diff --git a/docs/community/learning-algorithms.md b/docs/community/learning-algorithms.md new file mode 100644 index 00000000..b3f251d5 --- /dev/null +++ b/docs/community/learning-algorithms.md @@ -0,0 +1,14 @@ +--- +layout: "default" +title: "Learning Algorithms" +nav_order: 5 +parent: "Smart Control Project Documentation" +has_children: true +--- + + +# Learning Algorithms + +One of the goals of building a simulation environment like the one presented here is to use it to train learning algorithms to optimize control of that building. On that note, we provide implementation of a few learning algorithms implemented to explore this possibility. + +---- \ No newline at end of file diff --git a/docs/community/mcts.md b/docs/community/mcts.md new file mode 100644 index 00000000..166f4062 --- /dev/null +++ b/docs/community/mcts.md @@ -0,0 +1,37 @@ +--- +layout: "default" +title: "Monte Carlo Tree Search" +nav_order: 1 +parent: "Learning Algorithms" +grand_parent: "Smart Control Project Documentation" +--- + +# Monte Carlo Tree Search + +MCTS is not technically an RL algorithm, but can be attempted and leveraged as a potential baseline performance metric. + +In the proposed setup, each node in the MCTS tree is identified by a given sequence of actions taken since the episode's start. Nodes in different depths of the tree are a fixed number of `expand_steps` apart, such that the MCTS agent can only decide on a new action every `expand_steps` number of steps. + +Implementing MCTS in this setup comes with a few challenges, which we highlight here: + +## Slow Rollouts and Parallelism + +Typically, a rollout in an MCTS consists of choosing some default policy (e.g. random moves in a game), and then playing the episode to completion. In this case, doing this is very slow, as running an environment simulation is time consuming. Because of this, we only perform rollouts for a smaller fixed number of steps `rollout_steps` after the corresponding node's timestamp. + +To address this problem, we also adapt the implementation to support parallelism using `multiprocessing`. This was favored instead of multithreading due to the GIL lock. Because we are not dealing with async operations, multithreading should not provide a performance benefit, as only one thread is allowed to execute code at a time. Multiprocessing however, allows multiple distinct python processes, which should then obtain a speedup. + +The design of `SbsimMonteCarloTreeSearchNode` and `SbSimMonteCarloTreeSearch` was adapted in order to support `multiprocessing`. For example, since the node objects can't be serialized and thus can't be passed into workers, methods such as `SbsimMonteCarloTreeSearchNode.run_rollout` are made static to allow workers to execute them independently. + +## Node Selection + +As described above, our implementation performs many concurrent rollouts. To choose which nodes to expand, the method `SbSimMonteCarloTreeSearch.get_nodes_for_expansion` is used. This method chooses the `@ param num_nodes` nodes to expand by finding adding a node if it is not fully expanded, and then recursively calling itself on the node's children, in order from the highest to lowest score. The constant `@ param c_param` should control the balance between exploration and exploitation. + +## Node Evaluation + +Node evaluation: to evaluate a node, we consider its performance in comparison to the a baseline schedule policy. A node's score is given by the sum of the differences (when compared to the baseline policy return) of the rollout returns of all its children. To keep things fair, this is then normalized by the sum of the number of hours elapsed until the rollout end for all children. In summary, this means that each node is scored by the *average rollout return improvement per hour for all it's children*. + +--- + +[Back to Learning Algorithms](learning-algorithms.md) + +[Back to Home](../index.md) \ No newline at end of file diff --git a/docs/community/metrics-interpretation.md b/docs/community/metrics-interpretation.md new file mode 100644 index 00000000..b35c5a70 --- /dev/null +++ b/docs/community/metrics-interpretation.md @@ -0,0 +1,36 @@ +--- +layout: "default" +title: "Metrics Interpretation" +nav_order: 8 +parent: "Smart Control Project Documentation" +--- + +# Understanding the Logs in the Metrics directory + +The metrics files (observation response, action response, reward infos, zone info, and device info) are saved in the `metrics` path specified by you in the SAC_Demo notebook, organized by directories corresponding to different runs and each metric file corresponding to the metric for a single day. These can be read using the functions in smart_control.controller_reader.py, which starts by creating a ProtoReader with the path to the metrics directory. This section will explain the components of the different metric logs. + +## Observation Responses + +For every five minutes, i.e. 300 second differences between timestamps, this log first lists all observation requests, i.e. which measurements for which sensor (identified by the device id). +Then, it lists each observation response, which contains the timestamp, value for the measurement, and the validity of the measurement (true or false), as well as the corresponding request. +You can read the log file using ProtoReader.read_observation_responses(start_timestamp, end_timestamp). +Ex. reader = controller_reader.ProtoReader('dataset/SB1/19/') +reader.read_observation_responses(pd.Timestamp('2019-03-16T00:00:00'), pd.Timestamp('2019-03-17T00:00:00')) +Each timestamp in the result is of type protobuf.Timestamp, which can be converted to an interpretable pd.Timestamp object using the protos_to_pandas_timestamp() function in smart_control.utils. + +## Action Responses +Requests entail supply air temperature at two different devices and supply water temperature at one device, corresponding to action values. Responses detail how the given device is responding to requested new value. + +## Reward Responses +Split up into 5 minute intervals again, this provides the breakdown of the reward value at that time step. + +## Reward Infos +These are organized in 5 minute intervals, with each entry organized by zone ID corresponding to the zone info file. Each zone contains the measurements providing the values for the described metrics corresponding to the agent_id (ex. "baseline_policy") and scenario_id (ex. "baseline_collect"). + +## Device Info +This provides information regarding each device, identified by a unique device ID and code as well as its namespace and type. Each device has a specific set of observable fields and action fields that are listed underneath its identifiers. + +## Zone Info +Each entry represents a specific zone identified by zone_id and zone_descriotion, inside a building identified by building_id on the given floor. It also contains a list of IDs for the devices present inside the given zone. + +[Back to Home](../index.md) \ No newline at end of file diff --git a/docs/community/natural-gas-energy-cost.md b/docs/community/natural-gas-energy-cost.md new file mode 100644 index 00000000..c145215e --- /dev/null +++ b/docs/community/natural-gas-energy-cost.md @@ -0,0 +1,33 @@ +--- +layout: "default" +title: "NaturalGasEnergyCost" +nav_order: 5 +parent: "Reward Functions" +grand_parent: "Smart Control Project Documentation" +--- + +# NaturalGasEnergyCost + +**Purpose**: Models the cost and carbon emissions associated with natural gas consumption. + +## Key Attributes + +- `gas_price_by_month`: Gas prices by month. + +## Key Methods + +- `__init__(gas_price_by_month)`: Initializes the energy cost model with monthly gas prices. +- `cost(start_time, end_time, energy_rate)`: Calculates the cost of natural gas consumed over a time interval. +- `carbon(start_time, end_time, energy_rate)`: Calculates the carbon emissions from natural gas consumption over a time interval. + +## Calculation Logic + +- Uses monthly gas prices to determine the cost. +- Converts energy rates to costs and emissions based on standard conversion factors. +- Accounts for natural gas being used primarily for heating. + +--- + +[Back to Reward Functions](reward-functions.md) + +[Back to Home](../index.md) diff --git a/docs/community/occupancy-models.md b/docs/community/occupancy-models.md new file mode 100644 index 00000000..6bb6b724 --- /dev/null +++ b/docs/community/occupancy-models.md @@ -0,0 +1,33 @@ +--- +layout: "default" +title: "Occupancy Models" +nav_order: 4 +parent: "Simulation Components" +grand_parent: "Smart Control Project Documentation" +--- + +# Occupancy Models + +**Purpose**: Simulates occupancy patterns within the building, affecting internal heat gains and productivity. + +## Key Classes and Components + +- **`RandomizedArrivalDepartureOccupancy`**: + + - Models occupancy with randomized arrival and departure times. + + - **Attributes**: + + - `zone_assignment`: Occupancy level assigned to zones. + - `earliest_expected_arrival_hour`: Earliest possible arrival time. + - `latest_expected_arrival_hour`: Latest possible arrival time. + - `earliest_expected_departure_hour`: Earliest possible departure time. + - `latest_expected_departure_hour`: Latest possible departure time. + - `time_step_sec`: Time step in seconds. + - `time_zone`: Time zone for the simulation. + +--- + +[Back to Simulation Components](simulation-components.md) + +[Back to Home](../index.md) diff --git a/docs/community/regret-reward-function.md b/docs/community/regret-reward-function.md new file mode 100644 index 00000000..24a08740 --- /dev/null +++ b/docs/community/regret-reward-function.md @@ -0,0 +1,41 @@ +--- +layout: "default" +title: "SetpointEnergyCarbonRegretFunction" +nav_order: 3 +parent: "Reward Functions" +grand_parent: "Smart Control Project Documentation" +--- + +# SetpointEnergyCarbonRegretFunction + +**Purpose**: Implements a reward function that calculates regret based on deviations from optimal productivity, energy cost, and carbon emissions. + +## Key Attributes + +- Inherits from `BaseSetpointEnergyCarbonRewardFunction`. +- `max_productivity_personhour_usd`: Maximum productivity per person-hour in USD. +- `min_productivity_personhour_usd`: Minimum productivity per person-hour in USD. +- `max_electricity_rate`: Maximum electricity energy rate for normalization. +- `max_natural_gas_rate`: Maximum natural gas energy rate for normalization. +- `productivity_weight`: Weight for productivity in the regret calculation. +- `energy_cost_weight`: Weight for energy cost in the regret calculation. +- `carbon_emission_weight`: Weight for carbon emissions in the regret calculation. + +## Key Methods + +- `__init__(...)`: Initializes the reward function with parameters for regret calculation. +- `compute_reward(energy_reward_info)`: Computes the normalized regret based on productivity, energy cost, and carbon emissions. + +## Regret Calculation Logic + +- Determines the maximum and minimum possible productivity. +- Calculates the normalized productivity regret. +- Normalizes the energy costs and carbon emissions against their maximum values. +- Combines the normalized components using specified weights. +- Produces a final reward value representing the regret. + +--- + +[Back to Reward Functions](reward-functions.md) + +[Back to Home](../index.md) diff --git a/docs/community/reinforcement-learning-module.md b/docs/community/reinforcement-learning-module.md new file mode 100644 index 00000000..ef3c3179 --- /dev/null +++ b/docs/community/reinforcement-learning-module.md @@ -0,0 +1,25 @@ +--- +layout: "default" +title: "Reinforcement Learning Module" +nav_order: 10 +parent: "Smart Control Project Documentation" +--- +# Reinforcement Learning Module +## Structure +The reinforcement learning module is meant to have the code necessary to train and evaluate RL agents. It has the +following structure: +``` +smart_control/reinforcement_learning/ +├── agents/ # RL agent implementations (SAC, TD3, DDPG) +│ └── networks/ # Neural networks for agents +├── observers/ # Monitoring and data collection during training/evaluation +├── policies/ # Policy implementations (including baseline policies) +├── replay_buffer/ # Experience replay buffer management +├── scripts/ # Training and evaluation scripts +├── utils/ # Utility functions and helpers +└── visualization/ # Visualization tools for analysis +``` + +## Tutorials + +Check out this [tutorial](https://youtu.be/RbpkKciw0IQ) to help get started with the RL module. diff --git a/docs/community/reinforcement-learning-module/agents.md b/docs/community/reinforcement-learning-module/agents.md new file mode 100644 index 00000000..6e49d4f4 --- /dev/null +++ b/docs/community/reinforcement-learning-module/agents.md @@ -0,0 +1,130 @@ +--- +layout: "default" +title: "RL Agents" +nav_order: 1 +parent: "Reinforcement Learning Module" +grand_parent: "Smart Control Project Documentation" +--- + +# Reinforcement Learning Agents + +The RL agents module provides implementations of reinforcement learning algorithms tailored for building control applications. All agents follow the TF-Agents interface for consistency and interoperability. + +## Agent Interface + +All agents in the Smart Control framework implement the [`tf_agents.agents.tf_agent.TFAgent`](https://www.tensorflow.org/agents/api_docs/python/tf_agents/agents/TFAgent) interface, providing a consistent API for interacting with the models. + +## Agent Factory Functions + +The Smart Control framework provides factory functions for creating agents with sensible defaults: + +### SAC Agent + +```python +from smart_control.reinforcement_learning.agents.sac_agent import create_sac_agent + +# Create an SAC agent with default parameters +agent = create_sac_agent( + time_step_spec=time_step_spec, + action_spec=action_spec +) + +# Create an SAC agent with custom parameters +agent = create_sac_agent( + time_step_spec=time_step_spec, + action_spec=action_spec, + actor_fc_layers=(256, 256), + critic_obs_fc_layers=(256, 128), + critic_action_fc_layers=(256, 128), + critic_joint_fc_layers=(256, 128), + actor_learning_rate=3e-4, + critic_learning_rate=3e-4, + alpha_learning_rate=3e-4 +) +``` + +### TD3 Agent + +```python +from smart_control.reinforcement_learning.agents.td3_agent import create_td3_agent + +# Create a TD3 agent with default parameters +agent = create_td3_agent( + time_step_spec=time_step_spec, + action_spec=action_spec +) + +# Create a TD3 agent with custom parameters +agent = create_td3_agent( + time_step_spec=time_step_spec, + action_spec=action_spec, + actor_fc_layers=(256, 256), + critic_obs_fc_layers=(256, 128), + critic_action_fc_layers=(256, 128), + critic_joint_fc_layers=(256, 128) +) +``` + +### DDPG Agent + +```python +from smart_control.reinforcement_learning.agents.ddpg_agent import create_ddpg_agent + +# Create a DDPG agent with default parameters +agent = create_ddpg_agent( + time_step_spec=time_step_spec, + action_spec=action_spec +) + +# Create a DDPG agent with custom parameters +agent = create_ddpg_agent( + time_step_spec=time_step_spec, + action_spec=action_spec, + actor_fc_layers=(128, 128), + critic_obs_fc_layers=(128, 64), + critic_action_fc_layers=(128, 64), + critic_joint_fc_layers=(128, 64) +) +``` + +## Networks + +The networks used by each agent are kept in the `networks/` subdirectory in this module. + +## Adding a New Agent + +To experiment with different agents, you can create a new agent by adding a new agent file in the `agents/` directory, +and any necessary networks in the `agents/networrks/` directory. Follow the existing agents as a template, +and ensure that your agent implementation implements the +[`tf_agents.agents.tf_agent.TFAgent`](https://www.tensorflow.org/agents/api_docs/python/tf_agents/agents/TFAgent) interface to work out-of +the box. + +After that, any training script (e.g. `train.py`) to include this new agent, which is simply adding another item to +this part of the code: + +```python +# train.py script +... +# Add your agent implementation here +# Create agent based on type + logger.info(f"Creating {agent_type} agent") + if agent_type.lower() == 'sac': + logger.info("Creating SAC agent") + agent = create_sac_agent(time_step_spec=time_step_spec, action_spec=action_spec) + elif agent_type.lower() == 'td3': + logger.info("Creating TD3 agent") + agent = create_td3_agent(time_step_spec=time_step_spec, action_spec=action_spec) + elif agent_type.lower() == 'ddpg': + logger.info("Creating DDPG agent") + agent = create_ddpg_agent(time_step_spec=time_step_spec, action_spec=action_spec) + else: + logger.exception(f"Unsupported agent type: {agent_type}") + raise ValueError(f"Unsupported agent type: {agent_type}") +... +``` + +--- + +[Back to Reinforcement Learning](../reinforcement-learning-module.md) + +[Back to Home](../../index.md) diff --git a/docs/community/reinforcement-learning-module/observers.md b/docs/community/reinforcement-learning-module/observers.md new file mode 100644 index 00000000..b5c2c178 --- /dev/null +++ b/docs/community/reinforcement-learning-module/observers.md @@ -0,0 +1,81 @@ +--- +layout: "default" +title: "Observers" +nav_order: 5 +parent: "Reinforcement Learning Module" +grand_parent: "Smart Control Project Documentation" +--- + +# Observers + +Observers monitor agent behavior during training and evaluation by processing trajectory data at each step. Observers can be used to log information, visualize agent performance, or save data for later analysis. +They are designed to be modular by using the Observer design pattern, allowing you to easily add or remove observers to your agent/actor depending +on your needs. + +## Observer Interface + +All observers implement the `Observer` abstract base class, defined in `observers.base_observer.py`: + +```python +class Observer(abc.ABC): + @abc.abstractmethod + def __call__(self, trajectory: trajectory_lib.Trajectory) -> None: + """Process a trajectory.""" + pass + + def reset(self) -> None: + """Reset observer state between episodes.""" + pass + + def close(self) -> None: + """Clean up resources.""" + pass +``` + +## Available Observers + +The following observers are implemented and available. + +### PrintStatusObserver + +Logs training progress information to the console: + +```python +from smart_control.reinforcement_learning.observers.print_status_observer import PrintStatusObserver + +print_observer = PrintStatusObserver( + status_interval_steps=10, + environment=env, # tf environment + replay_buffer=replay_buffer # replay buffer being used. Used to print replay buffer size. + # Can be None if not using replay buffer +) +``` + +### TrajectoryRecorderObserver + +Records trajectory data for later analysis and visualization. This is very useful for evaluation runs: + +```python +from smart_control.reinforcement_learning.observers.trajectory_recorder_observer import TrajectoryRecorderObserver + +trajectory_observer = TrajectoryRecorderObserver( + save_dir=trajectory_dit, # directory where to save plots/data + environment=env # tf environment +) +``` + +### CompositeObserver + +Combines multiple observers into a single observer. This is useful to make it simpler to pass observers +to the agent/actor: + +```python +from smart_control.reinforcement_learning.observers.composite_observer import CompositeObserver + +combined_observers = CompositeObserver([print_observer, replay_buffer_observer]) +# now, just need to pass observers = combined_observers to the agent/actor +``` + +[Back to Reinforcement Learning](../reinforcement-learning-module.md) + +[Back to Home](../../index.md) diff --git a/docs/community/reinforcement-learning-module/policies.md b/docs/community/reinforcement-learning-module/policies.md new file mode 100644 index 00000000..b97c6f13 --- /dev/null +++ b/docs/community/reinforcement-learning-module/policies.md @@ -0,0 +1,52 @@ +--- +layout: "default" +title: "Policies" +nav_order: 2 +parent: "Reinforcement Learning Module" +grand_parent: "Smart Control Project Documentation" +--- + +# Policies + +Policies determine the agent's behavior by mapping observations to actions. Policies can be deterministic (e.g. greedy policies) or stochastic (e.g. exploratory policies). A policy can also be learned by an agent, +or it can be just a simple rule-based policy (e.g. a fixed building schedule). + +In this module, we provide two classes. `SchedulePolicy` is used to define rule-based policies that can be used as +baselines for RL agents. `SavedModelPolicy` is a wrapper used to load and interact with policies that have been +learned and saved. + +All of the policies in this project should [`tf_agents.policies.TFPolicy`](https://www.tensorflow.org/agents/api_docs/python/tf_agents/policies/TFPolicy) to provide a consistent interface to interact with policies. + +## SchedulePolicy + +**Purpose**: Implements traditional rule-based control strategies based on time schedules. + +**Implementation**: `SchedulePolicy` in `schedule_policy.py` + +**Usage Example**: see the implementation of the `create_baseline_schedule_policy` function in `policies/schedule_policy.py`, which +instantiates an example baseline policy. + +## SavedModelPolicy + +**Purpose**: Loads and uses a previously trained policy that has been saved. + +**Implementation**: `SavedModelPolicy` in `saved_model_policy.py` + +**Usage Example**: + +```python +from smart_control.reinforcement_learning.policies.saved_model_policy import SavedModelPolicy + +# Load a saved policy +policy = SavedModelPolicy( + saved_model_path="path/to/saved/policy", + time_step_spec=time_step_spec, # obtained through tf_env.time_step_spec() + action_spec=action_spec # obtained through tf_env.action_spec() +) +``` + +--- + +[Back to Reinforcement Learning](../reinforcement-learning-module.md) + +[Back to Home](../../index.md) diff --git a/docs/community/reinforcement-learning-module/replay_buffer.md b/docs/community/reinforcement-learning-module/replay_buffer.md new file mode 100644 index 00000000..53108002 --- /dev/null +++ b/docs/community/reinforcement-learning-module/replay_buffer.md @@ -0,0 +1,108 @@ +--- +layout: "default" +title: "Replay Buffer" +nav_order: 4 +parent: "Reinforcement Learning Module" +grand_parent: "Smart Control Project Documentation" +--- + +# Replay Buffer + +The replay buffer stores agent experiences for later reuse, enabling efficient learning from past interactions. + +This project provides a wrapper class around a Reverb replay buffer to facilitate interaction with it. + +## ReplayBufferManager + +The `ReplayBufferManager` class simplifies the creation and management of replay buffers: + +```python +from smart_control.reinforcement_learning.replay_buffer.replay_buffer import ReplayBufferManager + +# Create a replay buffer manager +replay_manager = ReplayBufferManager( + data_spec=agent.collect_data_spec, # agent is a TF-Agents agent + capacity=50000, + checkpoint_dir="path/to/checkpoint/dir", + sequence_length=2 +) + +# Create a new replay buffer +replay_buffer, replay_buffer_observer = replay_manager.create_replay_buffer() + +# Or load an existing replay buffer +replay_buffer, replay_buffer_observer = replay_manager.load_replay_buffer() +``` + +To add experiences to the replay buffer, you can add the `replay_buffer_observer` object returned above. For example: + +```python +# Combine observers + replay_buffer, replay_buffer_observer = replay_manager.load_replay_buffer() + + collect_actor = actor.Actor( + ..., + observers=[replay_buffer_observer], + ..., + ) +``` + +### Key Methods + +- **`create_replay_buffer()`**: Creates a new replay buffer and observer +- **`load_replay_buffer()`**: Loads an existing replay buffer from a checkpoint +- **`get_dataset(batch_size, num_steps)`**: Creates a TensorFlow dataset for sampling +- **`num_frames()`**: Returns the current number of frames in the buffer +- **`clear()`**: Clears all data from the buffer +- **`close()`**: Closes the buffer server and cleans up resources + +## Populating the Buffer + +### Initial Population + +To pre-populate the buffer with some initial experiences (e.g. training an off-policy algorithm) you can use the `populate_starter_buffer.py` script, at `scripts/populate_replay_buffer.py`. This uses the baseline schedule policy from `policies/schedule_policy.py` to pre-populate the buffer: + +```bash +# Populate a starter buffer using a baseline policy +python scripts/populate_starter_buffer.py \ + --buffer-name my-starter-buffer \ + --capacity 50000 \ + --steps-per-run 672 \ + --num-runs 10 +``` + +## Sampling from the Buffer + +For training, experiences are sampled from the buffer as batches: + +```python +# Create a dataset for sampling +dataset = replay_buffer.as_dataset( + sample_batch_size=64, + num_steps=2, + num_parallel_calls=3 +).prefetch(3) +``` + +## Checkpointing + +Replay buffers can be checkpointed to disk for persistence: + +```python +# Save the current state +replay_buffer.py_client.checkpoint() + +# Load from checkpoint (done through ReplayBufferManager) +replay_manager = ReplayBufferManager( + data_spec=agent.collect_data_spec, + capacity=50000, + checkpoint_dir="path/to/checkpoint/dir" +) +replay_buffer, observer = replay_manager.load_replay_buffer() +``` + +--- + +[Back to Reinforcement Learning](../reinforcement-learning-module.md) + +[Back to Home](../../index.md) diff --git a/docs/community/reinforcement-learning-module/scripts.md b/docs/community/reinforcement-learning-module/scripts.md new file mode 100644 index 00000000..5369de15 --- /dev/null +++ b/docs/community/reinforcement-learning-module/scripts.md @@ -0,0 +1,175 @@ +--- +layout: "default" +title: "Scripts" +nav_order: 7 +parent: "Reinforcement Learning Module" +grand_parent: "Smart Control Project Documentation" +--- + +# Scripts + +The `scripts` module provides command-line utilities for training, evaluating, and managing reinforcement learning experiments. These scripts streamline common RL tasks with standardized workflows. + +## Training Script + +`train.py` trains a reinforcement learning agent using a pre-populated replay buffer, managing agent creation, experience collection, and metrics logging. + +### Parameters + +| Parameter | Required | Default | Description | +|----------------------------------------|----------|----------------------------------|-----------------------------------------------------------------------------| +| `--starter-buffer-path` | Yes | N/A | Path to the pre-populated replay buffer | +| `--experiment-name` | Yes | N/A | Name of the experiment for saving results | +| `--agent-type` | No | `'sac'` | Type of agent to train: `'sac'`, `'td3'`, or `'ddpg'` | +| `--train-iterations` | No | `300` | Total number of training iterations | +| `--collect-steps-per-training-iteration`| No | `50` | Number of environment steps to collect per training iteration | +| `--batch-size` | No | `256` | Batch size for training (number of samples per gradient update) | +| `--log-interval` | No | `1` | Interval (in steps) for logging training metrics | +| `--eval-interval` | No | `10` | Interval (in steps) for evaluating the agent | +| `--num-eval-episodes` | No | `1` | Number of episodes to run during each evaluation | +| `--checkpoint-interval` | No | `10` | Interval (in steps) for checkpointing the replay buffer | +| `--learner-iterations` | No | `200` | Number of gradient updates to perform per training iteration | +| `--scenario-config-path` | No | `smart_control/configs/resources/sb1/generated_configs/config_timestepsec-900_numdaysinepisode-14_starttimestamp-2023-07-06.gin` | Path to the scenario configuration file (.gin) | + +### Example Usage + +```bash +python scripts/train.py \ + --starter-buffer-path data/buffers/initial_buffer \ + --experiment-name hvac_control_sac \ + --agent-type sac \ + --train-iterations 300 \ + --collect-steps-per-training-iteration 50 \ + --batch-size 256 \ + --scenario-config-path configs/custom_config.gin +``` + +## Evaluation Script + +`eval.py` evaluates a trained policy or the baseline schedule policy in a configured environment, producing performance metrics and optional trajectory data. + +### Parameters + +| Parameter | Required | Default | Description | +|-----------------------|----------|--------------------------------------------------------------|-----------------------------------------------------------------------------| +| `--policy-dir` | Yes | N/A | Path to the saved policy directory or `"schedule"` for baseline policy | +| `--gin-config` | No | `smart_control/configs/resources/sb1/generated_configs/config_timestepsec-900_numdaysinepisode-7_starttimestamp-2023-07-06.gin` | Path to the environment configuration file (.gin) | +| `--num-eval-episodes` | No | `1` | Number of episodes to run for evaluation | +| `--experiment-name` | Yes | N/A | Name of the evaluation experiment for saving results | +| `--save-trajectory` | No | `True` | Whether to save detailed trajectory data for each episode | + +### Example Usage + +```bash +python scripts/eval.py \ + --policy-dir experiments/hvac_control_sac/policies/greedy_policy \ + --gin-config configs/building_sim.gin \ + --num-eval-episodes 5 \ + --experiment-name sac_evaluation \ + --save-trajectory False +``` + +## Buffer Population Script + +`populate_starter_buffer.py` populates an initial replay buffer with exploration data using the baseline schedule policy, aiding off-policy learning. + +### Parameters + +| Parameter | Required | Default | Description | +|-----------------------------|----------|--------------------------------------------------------------|-----------------------------------------------------------------------------| +| `--buffer-name` | Yes | N/A | Name to identify the saved replay buffer | +| `--capacity` | No | `50000` | Maximum capacity of the replay buffer | +| `--steps-per-run` | No | `672` | Number of steps to collect per actor run (episode) | +| `--num-runs` | No | `10` | Number of actor runs (episodes) to perform | +| `--sequence-length` | No | `2` | Sequence length for storing trajectories in the buffer | +| `--env-gin-config-file-path`| No | `smart_control/configs/resources/sb1/generated_configs/config_timestepsec-900_numdaysinepisode-14_starttimestamp-2023-07-06.gin` | Path to the environment configuration file (.gin) | + +### Example Usage + +```bash +python scripts/populate_starter_buffer.py \ + --buffer-name initial_exploration \ + --capacity 100000 \ + --steps-per-run 1000 \ + --num-runs 20 \ + --sequence-length 2 \ + --env-gin-config-file-path configs/custom_env.gin +``` + +## Configuration Generator Script + +`generate_gin_config_files.py` generates multiple gin config files from a parameter grid for systematic experimentation. + +### Parameters + +| Parameter | Required | Default | Description | +|---------------------|----------|----------------------------------|-----------------------------------------------------------------------------| +| `base_config` | Yes | N/A | Path to the base gin config file (positional argument) | +| `--output-dir` | No | `'generated_configs'` | Directory to save the generated config files | +| `--time-steps` | No | `'300'` | Comma-separated list of `time_step_sec` values to grid over | +| `--num-days` | No | `'1,7,14,30'` | Comma-separated list of `num_days_in_episode` values to grid over | +| `--start-timestamps`| No | `'2023-07-06'` | Comma-separated list of `start_timestamp` dates to grid over | + +### Example Usage + +```bash +python scripts/generate_gin_config_files.py configs/base_config.gin \ + --output-dir configs/generated \ + --time-steps 300,600,900 \ + --num-days 1,7,14 \ + --start-timestamps 2023-07-06,2023-10-06 +``` + +## Typical Workflow + +A typical RL experiment workflow includes: + +1. **Generate configurations:** + + ```bash + python scripts/generate_gin_config_files.py configs/template.gin \ + --output-dir configs/generated + ``` + +2. **Populate initial buffer:** + + ```bash + python scripts/populate_starter_buffer.py \ + --buffer-name starter \ + --env-gin-config-file-path configs/generated/config_timestepsec-900_numdaysinepisode-14_starttimestamp-2023-07-06.gin + ``` + +3. **Train agent:** + + ```bash + python scripts/train.py \ + --starter-buffer-path data/buffers/starter \ + --experiment-name my_experiment \ + --scenario-config-path configs/generated/config_timestepsec-900_numdaysinepisode-14_starttimestamp-2023-07-06.gin + ``` + +4. **Evaluate trained policy:** + + ```bash + python scripts/eval.py \ + --policy-dir experiments/my_experiment/policies/greedy_policy \ + --gin-config configs/generated/config_timestepsec-900_numdaysinepisode-14_starttimestamp-2023-07-06.gin \ + --experiment-name eval_my_experiment + ``` + +5. **Compare against baseline:** + + ```bash + python scripts/eval.py \ + --policy-dir schedule \ + --gin-config configs/generated/config_timestepsec-900_numdaysinepisode-14_starttimestamp-2023-07-06.gin \ + --experiment-name baseline_evaluation + ``` + +--- + +[Back to Reinforcement Learning](../reinforcement-learning-module.md) + +[Back to Home](../../index.md) + +--- diff --git a/docs/community/reinforcement-learning-module/visualization.md b/docs/community/reinforcement-learning-module/visualization.md new file mode 100644 index 00000000..ebe5971d --- /dev/null +++ b/docs/community/reinforcement-learning-module/visualization.md @@ -0,0 +1,76 @@ +--- +layout: "default" +title: "Visualization" +nav_order: 6 +parent: "Reinforcement Learning Module" +grand_parent: "Smart Control Project Documentation" +--- + +# Visualization + +This part of the reinforcement learning module should include tools for visualizing agent behavior, environment states, and performance metrics. These tools help with understanding agent performance, debugging issues, and communicating results. + +## TrajectoryPlotter + +**Purpose**: Generates plots from trajectory data collected during agent evaluation. + +**Implementation**: `TrajectoryPlotter` in `visualization/trajectory_plotter.py` + +**Key Methods**: + +- **`plot_actions(actions, save_path, timestamps=None, title="Actions Over Time")`**: + + - Visualizes action values over time + - Shows the agent's control decisions + - Optionally includes timestamps on the x-axis + +- **`plot_rewards(rewards, save_path, timestamps=None, title="Rewards Over Time")`**: + + - Displays reward values at each time step + - Helps identify when the agent receives high or low rewards + - Useful for understanding the reward landscape + +- **`plot_cumulative_reward(rewards, save_path, timestamps=None, title="Cumulative Reward Over Time")`**: + - Shows the accumulation of reward over time + - Provides a clear picture of overall agent performance + - Useful for comparing different policies + +**Usage Example**: + +```python +from smart_control.reinforcement_learning.visualization.trajectory_plotter import TrajectoryPlotter + +# Generate plots from collected data +TrajectoryPlotter.plot_actions( + actions=action_data, + save_path='plots/actions.png', + timestamps=timestamp_data, + title='Agent Actions During Evaluation' +) + +TrajectoryPlotter.plot_rewards( + rewards=reward_data, + save_path='plots/rewards.png', + title='Agent Rewards' +) + +TrajectoryPlotter.plot_cumulative_reward( + rewards=reward_data, + save_path='plots/cumulative_reward.png', + title='Cumulative Reward' +) +``` + +These methods should produce plots similar to these: + +![Action Plot](../assets/visualization-module-images/action_plot.png) + +![Rewards Plot](../assets/visualization-module-images/reward_plot.png) + +![Cumulative Reward Plot](../assets/visualization-module-images/cum_reward_plot.png) + +--- + +[Back to Reinforcement Learning](../reinforcement-learning-module.md) + +[Back to Home](../../index.md) diff --git a/docs/community/reward-functions.md b/docs/community/reward-functions.md new file mode 100644 index 00000000..4fde4d66 --- /dev/null +++ b/docs/community/reward-functions.md @@ -0,0 +1,12 @@ +--- +layout: "default" +title: "Reward Functions" +nav_order: 4 +parent: "Smart Control Project Documentation" +has_children: true +--- + +# Reward Functions + +The reward functions define how the agent's actions are evaluated, guiding the learning process towards desired outcomes. +---- \ No newline at end of file diff --git a/docs/community/sac.md b/docs/community/sac.md new file mode 100644 index 00000000..08164f8a --- /dev/null +++ b/docs/community/sac.md @@ -0,0 +1,16 @@ +--- +layout: "default" +title: "Soft Actor Critic" +nav_order: 2 +parent: "Learning Algorithms" +grand_parent: "Smart Control Project Documentation" +--- + +# Soft Actor Critic +The implementation of this algorithm can be found in the `SAC_Demo.ipynb` notebook. + +--- + +[Back to Learning Algorithms](learning-algorithms.md) + +[Back to Home](../index.md) \ No newline at end of file diff --git a/docs/community/setpoint-reward-function.md b/docs/community/setpoint-reward-function.md new file mode 100644 index 00000000..f86f123b --- /dev/null +++ b/docs/community/setpoint-reward-function.md @@ -0,0 +1,40 @@ +--- +layout: "default" +title: "SetpointEnergyCarbonRewardFunction" +nav_order: 2 +parent: "Reward Functions" +grand_parent: "Smart Control Project Documentation" +--- + +# SetpointEnergyCarbonRewardFunction + +**Purpose**: Implements a reward function that balances productivity, energy cost, and carbon emissions. + +## Key Attributes + +- Inherits from `BaseSetpointEnergyCarbonRewardFunction`. +- `electricity_energy_cost`: Instance of `BaseEnergyCost` for electricity. +- `natural_gas_energy_cost`: Instance of `BaseEnergyCost` for natural gas. +- `energy_cost_weight`: Weight for energy cost in the reward. +- `carbon_cost_weight`: Weight for carbon emissions in the reward. +- `carbon_cost_factor`: Cost per kilogram of carbon emitted. +- `reward_normalizer_shift`: Shift applied to the reward for normalization. +- `reward_normalizer_scale`: Scale applied to the reward for normalization. + +## Key Methods + +- `__init__(...)`: Initializes the reward function with energy cost and carbon emission parameters. +- `compute_reward(energy_reward_info)`: Computes the reward value by considering productivity, energy costs, and carbon emissions. + +## Reward Calculation Logic + +- Calculates the productivity reward based on zone temperatures and occupancy. +- Computes the energy costs and carbon emissions for electricity and natural gas. +- Applies weights to each component (productivity, energy cost, carbon cost). +- Normalizes and combines these components to produce the final reward. + +--- + +[Back to Reward Functions](reward-functions.md) + +[Back to Home](../index.md) diff --git a/docs/community/simulation-components.md b/docs/community/simulation-components.md new file mode 100644 index 00000000..b53bfbcf --- /dev/null +++ b/docs/community/simulation-components.md @@ -0,0 +1,22 @@ +--- +layout: "default" +title: "Simulation Components" +nav_order: 3 +parent: "Smart Control Project Documentation" +has_children: true +--- + +# Simulation Components + +The simulation components model the physical building, HVAC systems, weather conditions, and occupancy patterns. + +## Sections + +- [Building Simulation](building-simulation.md) +- [HVAC Systems](hvac-systems.md) +- [Weather Controllers](weather-controllers.md) +- [Occupancy Models](occupancy-models.md) + +--- + +[Back to Home](../index.md) diff --git a/docs/community/system-architecture.md b/docs/community/system-architecture.md new file mode 100644 index 00000000..200cb441 --- /dev/null +++ b/docs/community/system-architecture.md @@ -0,0 +1,67 @@ +--- +layout: "default" +title: "System Interaction and Architecture" +nav_order: 7 +parent: "Smart Control Project Documentation" +--- + +# System Interaction and Architecture + +## Data Flow + +The system operates in discrete time steps within an episode, following the reinforcement learning loop: + +1. **Agent Action**: + + - The agent selects an action based on the current observation. + - The action is normalized and sent to the environment. + +2. **Environment Response**: + + - The environment applies the action to the building simulation. + - Actions are converted from normalized values to native setpoint values using action normalizers. + - The building simulation updates its state based on the action. + +3. **Observation Retrieval**: + + - The environment retrieves observations from the building after the action. + - Observations are normalized and processed, including time and occupancy features. + - Missing or invalid observations are handled using previous data or default values. + +4. **Reward Calculation**: + + - The reward function computes the reward based on productivity, energy cost, and carbon emissions. + - The reward is provided to the agent. + +5. **State Update**: + + - The environment updates internal metrics and logs information. + - Checks if the episode has ended based on the number of steps or time. + - If the episode has ended, the environment resets for the next episode. + +## Component Interactions + +- **Environment and Building Simulation**: + + - The `Environment` interacts with the `SimulatorBuilding`, which integrates the building simulation (`TFSimulator`), HVAC systems, weather controller, and occupancy model. + - Actions are applied to the building simulation, and observations are retrieved after each step. + +- **Reward Functions**: + + - The environment uses the reward function (e.g., `SetpointEnergyCarbonRegretFunction`) to compute rewards based on the `RewardInfo` from the building. + - The reward function accesses energy consumption data, occupancy levels, and temperatures to compute productivity and costs. + +- **Energy Cost Models**: + + - `ElectricityEnergyCost` and `NaturalGasEnergyCost` provide cost and carbon emission calculations based on energy usage and time. + - The reward function uses these models to compute energy costs and carbon emissions for the reward. + +- **Normalization and Configuration**: + + - `ActionConfig` defines how actions are normalized and mapped to building setpoints. + - Observation normalizers are defined for each measurement to ensure consistent scaling. + - Gin configuration files specify parameters and bindings for all components. + +--- + +[Back to Home](../index.md) diff --git a/docs/community/td3.md b/docs/community/td3.md new file mode 100644 index 00000000..4e3003f0 --- /dev/null +++ b/docs/community/td3.md @@ -0,0 +1,72 @@ +--- +layout: "default" +title: "Twin Delayed Deep Deterministic Policy Gradient" +nav_order: 4 +parent: "Learning Algorithms" +grand_parent: "Smart Control Project Documentation" +--- + +# Twin Delayed Deep Deterministic Policy Gradient (TD3) + +Implementation of TD3 can be found in the `TD3_Demo.ipynb` notebook. + +--- + +Twin Delayed Deep Deterministic Policy Gradient (TD3) is a model-free reinforcement learning algorithm for continuous action spaces. It improves upon DDPG by addressing overestimation bias and stabilizing training. Key features include: + +- **Delayed Policy Updates**: The actor network is updated less frequently than the critic networks. +- **Target Policy Smoothing**: Noise is added and clipped on target actions during critic updates. +- **Twin Critic Networks**: Two critic networks compute Q-values; the minimum is used to reduce overestimation. +- **Custom Actor Network**: A tailored actor scales outputs to valid action ranges. +- **Replay Buffer with Reverb**: A Reverb-based replay buffer stores trajectories for efficient off-policy learning. +- **TF-Agents Integration**: Leverages TensorFlow Agents for agent construction, training, and evaluation. + +## Agent Architecture + +### Actor Network + +- Built using fully connected layers (e.g., 128, 128 units) with ReLU activations. +- The final layer uses a tanh activation to scale outputs into the action space. +- Ensures actions remain within specified bounds. + +### Critic Network + +- Uses separate fully connected layers for observations and actions. +- Joins the outputs via a joint network to estimate Q-values. +- Implemented with two critics to select the minimum value for target computation. + +## Training Details + +- **Optimizers**: Both actor and critic use the Adam optimizer (learning rate = 3e-4). +- **Hyperparameters**: + - Discount factor (`gamma`): 0.99 + - Target update tau: 0.005 + - Target update period: 2 steps (delayed actor updates) +- **Noise Parameters**: + - Exploration noise standard deviation: 0.1 + - Target policy noise: 0.2 (clipped at 0.5) +- **Replay Buffer**: + - Capacity: 50,000 transitions + - Built with Reverb to sample batches and decorrelate training data + +## Training Loop + +1. **Data Collection** + The collect policy interacts with the environment to accumulate trajectories. + +2. **Gradient Updates** + The agent performs critic updates on every step and actor updates at a delayed frequency to improve stability. + +3. **Evaluation** + The eval policy is used to measure performance after each training iteration. + +## Noteworthy Aspects + +- **Stabilized Learning**: Target policy smoothing and delayed actor updates reduce variance and mitigate overestimation. +- **Efficient Off-Policy Learning**: The use of a Reverb replay buffer ensures diverse and decorrelated training samples. +- **Custom Network Design**: A bespoke actor network enforces action bounds, while twin critics improve Q-value estimates. +- **TF-Agents Framework**: Seamless integration with TF-Agents simplifies policy definition, training, and evaluation. + +[Back to Learning Algorithms](learning-algorithms.md) + +[Back to Home](../index.md) \ No newline at end of file diff --git a/docs/community/tutorials.md b/docs/community/tutorials.md new file mode 100644 index 00000000..9ecd80e4 --- /dev/null +++ b/docs/community/tutorials.md @@ -0,0 +1,16 @@ +--- +layout: "default" +title: "Tutorials" +nav_order: 11 +parent: "Smart Control Project Documentation" +has_children: false +--- + +# Tutorials + +Here we list some video tutorials that can help you get started with the Smart Control project. These tutorials cover different aspects of the project, including setting up with data, basic data analysis demo, +and reinforcement learning. + +- [Getting started with Reinforcement Learning in sbsimulator](https://youtu.be/RbpkKciw0IQ) +- [Setting Up with Data](https://youtu.be/474-33bLtAs) +- [Basic data Modeling Demo](https://youtu.be/GOhApaDYZmE) \ No newline at end of file diff --git a/docs/community/weather-controllers.md b/docs/community/weather-controllers.md new file mode 100644 index 00000000..d3b160e4 --- /dev/null +++ b/docs/community/weather-controllers.md @@ -0,0 +1,28 @@ +--- +layout: "default" +title: "Weather Controllers" +nav_order: 3 +parent: "Simulation Components" +grand_parent: "Smart Control Project Documentation" +--- + +# Weather Controllers + +**Purpose**: Simulates external weather conditions affecting the building. + +## Key Classes and Components + +- **`ReplayWeatherController`**: + + - Uses recorded weather data to simulate ambient conditions. + + - **Attributes**: + + - `local_weather_path`: Path to local weather data. + - `convection_coefficient`: Coefficient for heat convection between the building and the environment. + +--- + +[Back to Simulation Components](simulation-components.md) + +[Back to Home](../index.md) diff --git a/mkdocs.yml b/mkdocs.yml index 3627740c..a911f408 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -30,8 +30,8 @@ theme: - navigation.top # back to top button - navigation.footer # next and back buttons #- navigation.indexes # allows a directory to have an index.md - - content.action.edit # Enables the "Edit this page" button - - content.action.view # Enables the "View source of this page" button + - content.action.edit # Enables the "Edit this page" button + - content.action.view # Enables the "View source of this page" button favicon: assets/images/favicon.ico @@ -43,7 +43,6 @@ theme: # https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/ palette: - # Light Mode - media: "(prefers-color-scheme: light)" scheme: default @@ -70,37 +69,71 @@ theme: # nav: - - 'Home': index.md - - 'Local Development': - - 'Setup': - - 'Overview': setup.md - - 'Linux': setup/linux.md - - 'Mac': setup/mac.md - - 'Docker': setup/docker.md - - 'Contributing': contributing.md - - 'Documentation Site': docs-site.md - - 'API Reference': - - api/config.md - - 'Dataset': - - api/dataset/dataset.md - - api/dataset/partition.md - - api/environment.md - - api/models.md - - 'Reinforcement Learning': - - api/reinforcement_learning/agents.md - - api/reinforcement_learning/observers.md - - api/reinforcement_learning/policies.md - - api/reinforcement_learning/replay_buffer.md - - api/reinforcement_learning/scripts.md - - api/reinforcement_learning/utils.md - - api/reward.md - - 'Simulator': - - 'Overview': api/simulator/simulator.md - - api/simulator/building.md - - api/simulator/devices.md - - api/simulator/occupancy.md - - api/simulator/weather.md - - api/simulator/utils.md + - "Home": index.md + - "Local Development": + - "Setup": + - "Overview": setup.md + - "Linux": setup/linux.md + - "Mac": setup/mac.md + - "Docker": setup/docker.md + - "Contributing": contributing.md + - "Code of Conduct": code-of-conduct.md + - "Documentation Site": docs-site.md + - "API Reference": + - api/config.md + - "Dataset": + - api/dataset/dataset.md + - api/dataset/partition.md + - api/environment.md + - api/models.md + - "Reinforcement Learning": + - api/reinforcement_learning/agents.md + - api/reinforcement_learning/observers.md + - api/reinforcement_learning/policies.md + - api/reinforcement_learning/replay_buffer.md + - api/reinforcement_learning/scripts.md + - api/reinforcement_learning/utils.md + - api/reward.md + - "Simulator": + - "Overview": api/simulator/simulator.md + - api/simulator/building.md + - api/simulator/devices.md + - api/simulator/occupancy.md + - api/simulator/weather.md + - api/simulator/utils.md + - "Community Documentation": # NEW SECTION + - "Additional Resources": community/additional-resources.md + - "Base Reward Function": community/base-reward-function.md + - "Best Practices": community/best-practices.md + - "Building Simulation": community/building-simulation.md + - "Configuration": community/configuration.md + - "DDPG": community/ddpg.md + - "Electricity Energy Cost": community/electricity-energy-cost.md + - "Environment": community/environment.md + - "Glossary": community/glossary.md + - "HVAC Systems": community/hvac-systems.md + - "Learning Algorithms": community/learning-algorithms.md + - "MCTS": community/mcts.md + - "Metrics Interpretation": community/metrics-interpretation.md + - "Natural Gas Energy Cost": community/natural-gas-energy-cost.md + - "Occupancy Models": community/occupancy-models.md + - "Regret Reward Function": community/regret-reward-function.md + - "Reinforcement Learning Module": # NESTED SECTION FOR THE SUBDIRECTORY + - "Overview": community/reinforcement-learning-module.md # This points to the .md file in the folder + - "Agents": community/reinforcement-learning-module/agents.md + - "Observers": community/reinforcement-learning-module/observers.md + - "Policies": community/reinforcement-learning-module/policies.md + - "Replay Buffer": community/reinforcement-learning-module/replay_buffer.md + - "Scripts": community/reinforcement-learning-module/scripts.md + - "Visualization": community/reinforcement-learning-module/visualization.md + - "Reward Functions": community/reward-functions.md + - "SAC": community/sac.md + - "Setpoint Reward Function": community/setpoint-reward-function.md + - "Simulation Components": community/simulation-components.md + - "System Architecture": community/system-architecture.md + - "TD3": community/td3.md + - "Tutorials": community/tutorials.md + - "Weather Controllers": community/weather-controllers.md # # PLUGINS / EXTENSIONS @@ -133,7 +166,7 @@ plugins: handlers: python: paths: - - . # look in the current directory for the "smart_control" dir + - . # look in the current directory for the "smart_control" dir options: docstring_style: google docstring_section_style: "table" # "table", "list", "spacy" diff --git a/smart_control/dataset/dataset.py b/smart_control/dataset/dataset.py index 435f7ed1..331de1eb 100644 --- a/smart_control/dataset/dataset.py +++ b/smart_control/dataset/dataset.py @@ -78,7 +78,7 @@ def download(self, timeout=60): """Downloads the building's dataset from Google Cloud Storage. Only downloads and unzips the dataset if it doesn't already exist at the - expected [`building_dirpath`](./#smart_control.dataset.dataset.BuildingDataset.building_dirpath) + expected [`building_dirpath`](#smart_control.dataset.dataset.BuildingDataset.building_dirpath) location. Otherwise it will load the existing local data. Download speed is fairly quick, but unzipping takes a few moments. @@ -119,7 +119,7 @@ def floorplan(self) -> np.ndarray: + 1: wall / boundary + 2: outside / external space - Use the [`display_floorplan`](./#smart_control.dataset.dataset.BuildingDataset.display_floorplan) + Use the [`display_floorplan`](#smart_control.dataset.dataset.BuildingDataset.display_floorplan) method to view an image of the floorplan. """ return np.load(self.floorplan_filepath) @@ -149,7 +149,7 @@ def display_floorplan( show (bool): Whether or not to show the image. save (bool): Whether or not to save the image (as a .png file). image_filepath (str): An optional custom filepath to use when saving the - image. Only applies if `save=True`. By default, saves to the [`floorplan_image_filepath`](./#smart_control.dataset.dataset.BuildingDataset.floorplan_image_filepath) + image. Only applies if `save=True`. By default, saves to the [`floorplan_image_filepath`](#smart_control.dataset.dataset.BuildingDataset.floorplan_image_filepath) """ plt.imshow(self.floorplan, interpolation="nearest", cmap=cmap) if show: diff --git a/smart_control/dataset/partition.py b/smart_control/dataset/partition.py index ebfee3fc..0facd693 100644 --- a/smart_control/dataset/partition.py +++ b/smart_control/dataset/partition.py @@ -84,7 +84,7 @@ def metadata_filepath(self): @cached_property def metadata(self) -> dict: - """Metadata describing the partition [`data`](./#smart_control.dataset.partition.BuildingDatasetPartition.data). + """Metadata describing the partition [`data`](#smart_control.dataset.partition.BuildingDatasetPartition.data). Returns: A dictionary containing the following keys: @@ -146,9 +146,9 @@ def action_ids_map(self) -> dict: """A mapping of unique action identifiers. Returns: - A dictionary where the keys are the [`action_ids`](./#smart_control.dataset.partition.BuildingDatasetPartition.action_ids) + A dictionary where the keys are the [`action_ids`](#smart_control.dataset.partition.BuildingDatasetPartition.action_ids) and the values are unique integers referencing column indices in the - [`action_value_matrix`](./#smart_control.dataset.partition.BuildingDatasetPartition.action_value_matrix) + [`action_value_matrix`](#smart_control.dataset.partition.BuildingDatasetPartition.action_value_matrix) For example: @@ -167,9 +167,9 @@ def observation_ids_map(self) -> dict: """A mapping of unique observation identifiers. Returns: - A dictionary where the keys are the [`observation_ids`](./#smart_control.dataset.partition.BuildingDatasetPartition.observation_ids) + A dictionary where the keys are the [`observation_ids`](#smart_control.dataset.partition.BuildingDatasetPartition.observation_ids) and the values are unique integers referencing column indices in the - [`observation_value_matrix`](./#smart_control.dataset.partition.BuildingDatasetPartition.observation_value_matrix). + [`observation_value_matrix`](#smart_control.dataset.partition.BuildingDatasetPartition.observation_value_matrix). For example: @@ -190,8 +190,8 @@ def reward_info_ids_map(self) -> dict: See: `RewardInfo` in "smart_control/proto/smart_control_reward.proto". Returns: - A dictionary where the keys are the [`reward_info_ids`](./#smart_control.dataset.partition.BuildingDatasetPartition.reward_info_ids) - and the values are unique integers referencing column indices in the [`reward_info_value_matrix`](./#smart_control.dataset.partition.BuildingDatasetPartition.reward_info_value_matrix). + A dictionary where the keys are the [`reward_info_ids`](#smart_control.dataset.partition.BuildingDatasetPartition.reward_info_ids) + and the values are unique integers referencing column indices in the [`reward_info_value_matrix`](#smart_control.dataset.partition.BuildingDatasetPartition.reward_info_value_matrix). For example: @@ -212,8 +212,8 @@ def reward_ids_map(self) -> dict: See: `RewardResponse` in "smart_control/proto/smart_control_reward.proto". Returns: - A dictionary where the keys are the [`reward_ids`](./#smart_control.dataset.partition.BuildingDatasetPartition.reward_ids) - and the values are unique integers referencing column indices in the [`reward_value_matrix`](./#smart_control.dataset.partition.BuildingDatasetPartition.reward_value_matrix). + A dictionary where the keys are the [`reward_ids`](#smart_control.dataset.partition.BuildingDatasetPartition.reward_ids) + and the values are unique integers referencing column indices in the [`reward_value_matrix`](#smart_control.dataset.partition.BuildingDatasetPartition.reward_value_matrix). """ return { "agent_reward_value": 0, @@ -344,9 +344,9 @@ def actions_df(self) -> pd.DataFrame: """A time-series dataframe of numeric action values, constructed from the following components: - + Columns are the [`action_ids`](./#smart_control.dataset.partition.BuildingDatasetPartition.action_ids) - + Row indices are the [`action_timestamps`](./#smart_control.dataset.partition.BuildingDatasetPartition.action_timestamps) - + Cell values are from the [`action_value_matrix`](./#smart_control.dataset.partition.BuildingDatasetPartition.action_value_matrix) + + Columns are the [`action_ids`](#smart_control.dataset.partition.BuildingDatasetPartition.action_ids) + + Row indices are the [`action_timestamps`](#smart_control.dataset.partition.BuildingDatasetPartition.action_timestamps) + + Cell values are from the [`action_value_matrix`](#smart_control.dataset.partition.BuildingDatasetPartition.action_value_matrix) Returns: A `pandas.DataFrame`. Here is an example of the structure: @@ -373,9 +373,9 @@ def observations_df(self) -> pd.DataFrame: """A time-series dataframe of numeric observation values, constructed from the following components: - + Columns are the [`observation_ids`](./#smart_control.dataset.partition.BuildingDatasetPartition.observation_ids) - + Row indices are the [`observation_timestamps`](./#smart_control.dataset.partition.BuildingDatasetPartition.observation_timestamps) - + Cell values are from the [`observation_value_matrix`](./#smart_control.dataset.partition.BuildingDatasetPartition.observation_value_matrix) + + Columns are the [`observation_ids`](#smart_control.dataset.partition.BuildingDatasetPartition.observation_ids) + + Row indices are the [`observation_timestamps`](#smart_control.dataset.partition.BuildingDatasetPartition.observation_timestamps) + + Cell values are from the [`observation_value_matrix`](#smart_control.dataset.partition.BuildingDatasetPartition.observation_value_matrix) Returns: A `pandas.DataFrame`. Here is an example of the structure: @@ -402,9 +402,9 @@ def rewards_df(self) -> pd.DataFrame: """A time-series dataframe of numeric reward values, constructed from the following components: - + Columns are the [`reward_ids`](./#smart_control.dataset.partition.BuildingDatasetPartition.reward_ids) - + Row indices are the [`reward_timestamps`](./#smart_control.dataset.partition.BuildingDatasetPartition.reward_timestamps) - + Cell values are from the [`reward_value_matrix`](./#smart_control.dataset.partition.BuildingDatasetPartition.reward_value_matrix) + + Columns are the [`reward_ids`](#smart_control.dataset.partition.BuildingDatasetPartition.reward_ids) + + Row indices are the [`reward_timestamps`](#smart_control.dataset.partition.BuildingDatasetPartition.reward_timestamps) + + Cell values are from the [`reward_value_matrix`](#smart_control.dataset.partition.BuildingDatasetPartition.reward_value_matrix) Returns: A `pandas.DataFrame`. Here is an example of the structure: @@ -430,9 +430,9 @@ def reward_infos_df(self) -> pd.DataFrame: """A time-series dataframe of numeric reward info values, constructed from the following components: - + Columns are the [`reward_info_ids`](./#smart_control.dataset.partition.BuildingDatasetPartition.reward_info_ids) - + Row indices are the [`reward_info_timestamps`](./#smart_control.dataset.partition.BuildingDatasetPartition.reward_info_timestamps) - + Cell values are from the [`reward_info_value_matrix`](./#smart_control.dataset.partition.BuildingDatasetPartition.reward_info_value_matrix) + + Columns are the [`reward_info_ids`](#smart_control.dataset.partition.BuildingDatasetPartition.reward_info_ids) + + Row indices are the [`reward_info_timestamps`](#smart_control.dataset.partition.BuildingDatasetPartition.reward_info_timestamps) + + Cell values are from the [`reward_info_value_matrix`](#smart_control.dataset.partition.BuildingDatasetPartition.reward_info_value_matrix) Returns: A `pandas.DataFrame`. Here is an example of the structure: