From 29e8e14cc142451c078ff0fc4549ccb88763469d Mon Sep 17 00:00:00 2001 From: "sergi.e" <59253112+sergi-e@users.noreply.github.com> Date: Fri, 3 Apr 2020 13:57:11 +0200 Subject: [PATCH] Sergi e/rss docs (#2686) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * RSS first add * RSS docs first draft.· * Second draft. * Codacy fixes * Readme update --- Docs/adv_rss.md | 128 ++++++++++ .../rss_carla_integration_architecture.png | Bin 0 -> 246765 bytes Docs/index.md | 2 + Docs/python_api.md | 182 +++++++++++-- Docs/ref_sensors.md | 239 ++++++++++++++---- PythonAPI/docs/sensor.yml | 151 +++++++++-- PythonAPI/docs/sensor_data.yml | 186 +++++++++++--- README.md | 2 +- mkdocs.yml | 1 + 9 files changed, 773 insertions(+), 118 deletions(-) create mode 100644 Docs/adv_rss.md create mode 100644 Docs/img/rss_carla_integration_architecture.png diff --git a/Docs/adv_rss.md b/Docs/adv_rss.md new file mode 100644 index 000000000..d14527c2c --- /dev/null +++ b/Docs/adv_rss.md @@ -0,0 +1,128 @@ +# RSS Sensor + +CARLA integrates the [C++ Library for Responsibility Sensitive Safety](https://github.com/intel/ad-rss-lib) in the client library. This feature allows users to investigate behaviours of RSS without having to implement anything. CARLA will take care of providing the input, and applying the output to the AD systems on the fly. + +* [__Overview__](#overview) +* [__Compilation__](#compilation) + * [Dependencies](#dependencies) + * [Build](#build) +* [__Current state__](#current-state) + * [RssSensor](#rsssensor) + * [RssRestrictor](#rssrestrictor) + +!!! Important + This feature is a work in progress. Right now, it is only available for the Linux build. + +--- +## Overview + +The RSS library implements a mathematical model for safety assurance. It receives sensor information, and provides restrictions to the controllers of a vehicle. To sum up, the RSS module uses the sensor data to define __situations__. A situation describes the state of the ego vehicle with an element of the environment. For each situation, safety checks are made, and a proper response is calculated. The overall response is the result of all of the combined. For specific information on the library, read the [documentation](https://intel.github.io/ad-rss-lib/), especially the [Background section](https://intel.github.io/ad-rss-lib/ad_rss/Overview/). + +This is implemented in CARLA using two elements. + +* __RssSensor__ is in charge of the situation analysis, and response generation using the *ad-rss-lib*. +* __RssRestrictor__ applies the response by restricting the commands of the vehicle. + +The following image sketches the integration of __RSS__ into the CARLA architecture. + +![Interate RSS into CARLA](img/rss_carla_integration_architecture.png) + +__1. The server.__ + __-__ Sends a camera image to the client. (Only if the client needs visualization). + __-__ Provides the RssSensor with world data. + __-__ Sends a physics model of the vehicle to the RssRestrictor. (Only if the default values are overwritten). +__2. The client.__ + __-__ Provides the *RssSensor* with some [parameters](https://intel.github.io/ad-rss-lib/ad_rss/Appendix-ParameterDiscussion/) to be considered. + __-__ Sends to the *RssResrictor* an initial [carla.VehicleControl](python_api.md#carla.VehicleControl). +__3. The RssSensor.__ + __-__ Uses the *ad-rss-lib* to extract situations, do safety checks, and generate a response. + __-__ Sends the *RssRestrictor* a response containing the proper response and aceleration restrictions to be applied. + __-__ Asks the server to do some debug drawings to visualize the results of the calculations. +__4. The RssRestrictor__ + __-__ If the client asks for it, applies the response to the [carla.VehicleControl](python_api.md#carla.VehicleControl), and returns the resulting one. + +!!! Important + Debug drawings can delay the RSS response, so they should be disabled during automated RSS evaluations. Use [carla.RssVisualizationMode](python_api.md#carla.RssVisualizationMode) to change the visualization settings. + +[![RSS sensor in CARLA](img/rss_carla_integration.png)](https://www.youtube.com/watch?v=UxKPXPT2T8Q) +
NP+bx-H$pY zUEjC=GeMwdT#wpw5l+B4CW?kGpuKiC )}wi_SrO5G C3eJ{5Koi&Ba*O~#U6XrrG zaS<>4FdfX?;RNE~{A5lZ>M6A&`Ega~uD0rT`zoB@yu37lx+-qKZ)}bZ>m$3upG zmS*woNbwz0k$0Dgr*!7zMF{pi{H=Osogd*XW1@TSR<^BhVzEBs;GLUw;%xK92T$d~ z*Nbilx~nXGv&`waW||d0*1o$9p2Z$p={OkM*Pg_uHlKMXNIf}pDVI(8W=rGYphY{% z)hh$Kq_g1B`o_fvE+4LL01R6E0c#}W!nISrG}iX<3GH44x5_iQsW8u0Y4A?5Jh5^D z7v-7!+lY;aN@k@^6?6uaIYv@wMe_E83QR>aw8J>_Q=(H!lM>qkWq3mvQa*)g RnK>8_VxiF zXUp*I&c`R|FX zf7|LL*lUrLOb}-nOtPy)S2 BTqbFZzh-(!EIleS~g1qH2N&TCq@}FED7mMDj8l zGQYo4W25avhTT@Jdo0^3D_q2(Codx(!#_=$*3dp&%CC1s@^HUrfSg`jBTe6i8Rpr} z@=OG0mTF4bY3$P|)fF#{O()&(C$4W>z2Mr@klUPs!<-ooBoZ?3#KqZ3(y-ZpO|xP< z@Y9eyluEO&+i;=cl%Tsya8Pe5tOvk< GJE1#vEGC(v3}vk?nV zxsJbYm3NY`a~^ tPw5i*a@*>M z<^dZKt)_3b9RTl@3Hg=^Q`fcD2B-K9k30W8mvQkizXB ;)+e<%*IEPWne z`5wnLz^sq2C&v|_$)Cy_1>BcB)>E~ z2%eGp)XK%c2ZN2em*V;b14i5nyB)E+9`9{jTD=ZYw$gmXaOsWUmXb{9_^v&1+c8-W zfN_g<(Fyt82*a02CjocJ=hv22aX}Pe98~DV71_<0b39LseE>lN-HXL>>}^4JQj{%u zs#BxW!@312>&~y)4ol(_4VDikdxc(Zu@}yHVke)D_KuH=G<2*CQ?PsTnm&9YPuD|4 ztGB~&vD5rR*g$WP%K +sDKq<+OpZazvK76_HJrQw3s##5z%z5>um_K)NEL>+(N@)eSoS1VQhbJbQGb# zf4Vc}C<_)xDJd!8OoE %8Ld&$^(`8cu30Jn2~QiL5faE;|Ukw)R%aPtI91io6ah0TX1< zb`~$8;Tvs9H4tRbx7(JuQ#|R?lkt*l)3zj(rvWil)bH8GT@*EWSdJ)`L7Qj--;Hhw zbnvk%=oVU%s-J6+;m0w%s~k5=b31syxj|Cnb7g}W*-JVbTYfxNyeCkH21nfw3 zg~xQ19qN9N#Haru06*fLU}Es=h_m#UClZ{QHU3=_eFUlsp;ZB6SBs@{dI3wSwg@ZN z#lf%VBv4X)a@K6baQ?EKf58HhYVkpuGR01-Q(M0 g^ zMS@rrY`7R9>%YPXIGZs*pvaS$jxb8L9^>_c!^7`AYY4bu@dLkCQehNPybm&L;$TDh zri`wlnLMT>{N|&~{P^&c=Nb(j-H{AA%9(-rXVd9YxZq@AZPsKFPuS=wCnsl-aStH@ z(+5xpDQ|Soof+Y$kH`eh>Bzyhgj$*{wz2qH5vCwcP%J}m6u#I`-{WB(vA#z-rAx&g z9+FoQia!nW+Q9Eo={1p7^Ej5eq2FBS*eUEQwA(k#b91;LVNOo=73`6e#rSHw8Ptd8 za cG~S)q*wj O {jgm>$||q!sa#Js z${Q*UOU;CP$;a}M`i{zWaaT?fR^p`xy7tPWFk3A*ErDJg=Jec)W6So~PApTQt;etX z1ehzPWD;7r@Gs>*qWk$KM$8p>h?v$0qL{57D~Oks#8D#KUJ(5)@%0TXEm=@Ct4SzF zL`TIrW7?1)L_BZ*wwEhld(pqoi_~J{?N1hAlZAjtdB7Kysr^D{WCglo^%bd(raWA| zm06_MEAO5D2~ZHXho?PbSE*ZWiBSo65YQ&g**xTI@w#Yi6X3|+;=BEYXv-(0Y`U*q z369{%^ GU+_^iE6-tV7qV_UwS+y7QQ?SL#%@W19Z3c=8 zT?f@uiINO6WyY$5@Kd4ZQT5@e{B?wBLL+KA#an?1u^-(Rg^O+{p>A!wl72&~3tpkJ zsj=@ae?LTI@R Gjap)VgxazJ-AVXBc5*@W^+NgPu^?U3r@n2p}UXe95b*Dvqoa1 Ns89JL T&SZTWuQ* JAZRxHHl4zfy-Ftq {1dE=^-wA`VK+xzZIH|XFrxt-v5~$Z zHCyMW`%(1v=@@aBYgD6|;84gt-AcG$p5fUd_AOujxI3CaKh2US)PahlEYr(%n?kGM z2Tp7*1; H6GZUep4iM@p#g;-BV!*PBM~~u}6VH}wS8|5-7iKfjekD?Nx^6G{ zeVaJ=^_q<~2}t|)(hEL|Q6B3mqL-C#gNlY&6na5URHfAr(vj(61!z4jv4o6FGYChW zR|f1Of8srD@dKon xN@KnW0FJyr%p))@%8xOzYRJP8+nI1nk2YNR)rQAHfyHpDRyjWb^>h@R+i|LH6_c zxl8TUVUG)tTrkRsPi7w*9#%m|C@Cqq7AOD?c~;iGOGhYqb>>9sGX#*ywu`n07`nq> z>6Z@NPKC%e{izKjlH<|XUu;bHoXp>f00CjSnpIN)kAys(B3aQ%Yfv_*bF#;w;^)Rk z73=FHY35boFoJ9FH>u8ju<(a~lk1WgQ6YIYdSvXwU{l5jbG{b!r|c>hI0hdUX==eG zStp;1O4b#&&Bt7&mfwz!AWJhHbKjzmSO^2i{3fmV`Q2tH1VXhiC3 F&|JM6pr*(*1zu*z5wyw^0 zEBbVm@c~*rkOzz?i8lv=mE7i|%QqZi&6h5#f8aAGX7?wn4_)lj?48o} zf9Ekvhj)-|r9W0>q~Yte$<>3A;dhZR-lrh$WN_OiFx23`^ILwoG~^evUO7e#caoXA zD&v@_p#R!TTA6<3_$)7~v)&AB2m9L1l8>cld8kztz!*h^o&ipg*c5f&y_3;{pd;kj z9eLw>*}Opf^3BPC`$`2- ds`yTioG!MKkl5nH<7f}p@AKfDHzs]wqZ%c(Zc<)$AazkmP6u=Pr1 zJ&s$i)yXXDsMd1wHR2)bY!qF3;<(!6F1V;rbsp(2I!Ss7*pvSp+4hui+E?97g(*M| zyV7nY&?-0Dup_i |;g=4+lqs1RLX0%XOH@XyXzamP4LNtmDeDhPm*UM-> z8(a >DW7m&=R;(1leBs?R>?hQ63XDN%WO z=Zd`1egs}ICE5XZ!+ZJPE_y=ojbT!bAw)ax!~nQ=uryEZGAPh~ lUJ`M;o!=4?`;n->DM1ha2D+B;sgmx=LCH&Y? #!pqc@PtX-IcbF$A~Y>(+5kh?Vfu~3!sqV z>O^pc-KGm@4X#SizV96!*;nG$NiwdIJU6+o2zHu}&(Q0Ibpp z=8SxgVlOJr`!HWI^?s7)jVoY{O8rR!6SoTnernWeHvUn|MuKMx7JS%U+zL}_oHn{d zsS?~>mLqV++hG~kWeoY|ARsr}+W*aJ*F>GdhXAU?I^xtvrB$1IoooR=+fAKY<)mM# ze+mS87guLMrOEE+H`NAnNhg6#kF?=aC}}?t*g&q`PnX$aEFtnF4LcR1z~Q#6L2`Gf zd<1O@5U2C4Q3R^&wa)SDx9 yh_^if)lVo zq^aaovU9hN7eTXjA7q;BM{L~{qaja7{p%L@h^Et(>=%VESlYq|?Cr?s0K}r|e%bDQ znPp8{%_?}GvgnEvicQo416}^$g797j?F_?e@retCMJ=fJv(_VaDJGmF#>W(Q>Z_Rr z{BB7r$!Xg3GEQc9@Yoa}@ogQgT_5;Z399~{Ex4p{+|08odKZT)#aw=Y0|Sc3n m)%2j;%$E ScCJClCRwl?dT%PZywG~6-?we>PD*D>>@#p@8yj_v3L zr(u$Z1NJRu{OSDW+S>HmCPTs#^^;%f&g=z?dWnS6l$;M?8c@9emxM{h*)yfEa|^0N zCRoug9S?$}AM%jo=Zu%xBs1h| c@Dy{5Dd P!cAp$qrP!`YPmL93t3_cyTlH(#NV$1+U2fSj=yD0uaP#T@G*Gu} z*ZYhzbMeCdKcLF0zBuoE2@sGdiOt0+&W%46Vl}-jx1M9&5(1+6LQ}nu{`Fxq=^rAN zW3J2f=X?c wodNg^md{@glAh0Y@xgsm)FRg-2vE+LZ$Bl>splNgIz2vqD< Mmc4q-MTt@(o&n0m)v2aVo+}d|+1Ic?ys=nM%i%+}Mr&^Z za&W-W7C5#6B%exRq=Am5=I8$#o|0EeZes3bl>HXQtRxtt)@r{AKsMmwp)uiTSZ7H} z&lGjkA67EWOK4vLvY+Mbe+{*N&SQ3j&(Yfl2wX-XO6avgUX9l8mX+rJ&plE9SGJ^} z-MCHQ+JN3OtnBHVl%3B{om6q-{jCgKOY1xTqWRzJ{_kj7P&kpD(7b yPoo}S6hh;eZ_S-ecb*ufwm~`YWw21fXlpvpwye(+<)nS## zBpn` DhS}lY_bQy2 QIXe|9j--7%{+HLQ!?(cZULTL*P zr;*bgI;8TVhU7{1+C_6fbS~0zl~zX*L#-(P5gMWaG=h$x^0%G`aFC@dXv#*N?X~yR zqB`>|{CJ#=_TRPm=PR}d@&W8HY&x4(&ncj_u*GTNs+a3!f_$_wHP`7k`Yj6V!uND{ z90g`BpN9%TKH^GpdgE6FL@ClLdp_(mQs)-D`YE2uA|%3?KB%4jQ?%ER<40Wq*~4r3 z9aHimPmP@%wrj(QOAb@ =?g93y=i6QzCLR(K#DTJ&SHuyiH z&ATW)ItE&7sBCB#6iy5ktziqreatTKc2Oc(-9gjg0R@x7d}5=EDsdSpppo^x*OMVK zyaZd3_}4wp)h&V`iUKSGv=v8N1Bs^mTaP8Bl43G>Z>+rvC`v8)W}oa-GxK?W!&`d= z+j5;Sp&lH=qNuLVN$_ 0Rk&t_$f+>;mcW^;JY&Iom~Hysl%no=Nh0SkB0~Yl3wqu z!zV;mS^7< L8(@Fq#wh#o@SIM#kK5*?`>&5QEE{!wDEh z@2WyWq)`&tGAp;ff>-Qt=)i)B2>wsdcvl7QZhnvIzXk|8iTgFlWswi;_MoC8_8znu z?w0pdn>?}*NCZ_p?HF`B6(!-rSL(1@jG+=(u~-25QS^3h% @23RnMCJCW{MyDwrmA~u#GH#>&q=Mv!%7$NB`bAe|$aSyPnIt*=7OqoEdyj zAv7fGbbCL+`6LmzQIJka)4==wg0A1Lm~9bD+}A6)21|~Cx`YHjKb5nd%T5CJ!U@m! z<+{aNnDyk9sBPO4?s@Ud`P{b2;~lC+A+jzJkmt^`_vMhi0}hWwV_f}LPEkjbz9X*^ z)VR9CrZcgFH!1=BnLqVG J8r{noXzy}WD@6po`@v@{Ia9=VTyh%zp0gE1#jt3QMwZA+-zAn;nYZofo{+_VI ze3pDVvXAb$BR-(Ky#~}IkF=bh^}Dw%ldv}cG5NkP_20gS?rlhV`t>96{u1v0K5FCc zLl`NGt}Qs~H 4zEeAw^f+-SWcea9R$4q}X+ zlRGV==P;J+#YMRE1p|aUsoLwp>UI6UO+o)Y@~n4%Zh>kDyNTWu+{k0lTJu9Am@|Yy zofh3Mp^M^j^C@!1ZIo&P0=T)6Hg%NjY?JUWCA>q5?n5`ot!HQmd32Pc)s`{a^F!@O z$|?cm!Q-&A83)PoWI|^QAX*q%2G=ARx9X$15DW}Djgs7x3|J5Hwtae>fWU~|ko0}X zHq#~-*CZJ5-zRt)=pka8`V5Fydy>_P&(eoMwr= w|vdZFnzM(6-(XQp+9QB>V1^VVjcu2gFaWX?PEu}J@MOK6C(!P+p=uC z2MECO?GRAaX?d=91Moh8=mc^u9)y`exT4Mn_J*k=|N9&KX>CRV$-U%L`N$Q9958yX zWFMx_4)wv*FYR&X1)SXsV*{gBevdc2<6BQK {YA`XJ-SY _HR{YvC`JL}3yLg}XBRltP$B1tO3?BTNco%OjL z^WVcy>$w%%6D#4+aKVq`W*7*by@X4qGejgM!Q{tYk``Xli7h?B3SmMz5MzfNjgn1F zqh6@qUAG*9na?^%;Hu^qUrzlzj$>5_WB|;qy{}Z24D{3l2*OnQ9s>qWOOtt}3zOVz zzP0JP#>5BM50wFwlJ$~U*+}MyZ{K0KYS!6?>Eox( @;5BbiO zVMDe>8cN&mLRr@Nf5O0jcK|(}^ZEU4I{!3S!&6g1oA;@|+UDQ8^f{7nh03PbKJsff zW8ez$vm903s>+j3Hg=8&eN6lbEou6pR6PSW{n)RUjIJr?pEdl#bXzR)LaQDMw9aU| zOzH3HSFs(HYk#M*{1CfI{8g>i&?pxJ(;_5w=-Dol{Jdq{1h^!|jNJdO%Z5VMiKa_q z@Q~J1wOed#E-0-5UOmxDu&5j>Tar@&xT_{&YN_y!_73sm3qM`5ZJ#jx+qNk?Z6U52 zH~B>xk6B)&-4+w*lOh+B?;!sZ;ARQV8phS@(YM@xO}D@?o1xKV;F;B-E%vFp-0~+t zKn_ykpA?KkC0Ntl`Z)x7r<0|CLjCWt3Y2dIPhXrROGGv5MOv_f;^I(KbGdW&)tzme zNW(s7ZSa|X3YvSrLkcoZrX>yY&N^{0B@ W$++`u2V8? zR6m`=ouxvaXE=L% XQ)lUMA@XE zZYR9+QneSK2I}Q!!u*=|&@H8GixRCbtz)(Te&P?Z+Ne^g)K)3Ad^uTHfR)JbTm-hl zT99qj*?4Ii)$#l RwmM5~nY>V+y@~eF-}TR)tUjF2YRvqh#3D)KK+hdFY~byv^~fjZ8F% z1P`X;Zr?I}x
wdP!N%^i*!({W9LfPk?17hY6~vrT-8E>i`2F46#bk(Otjt7dG$7vmYqj=427 zapjj@HrEYn-|P_jbHClGm*9cAYO@w`HiI`%nW0p-C2rnpK{K)b-aFmDfI3@jb^hp| z=~7yHty&msYio~_VTp%s6RO;443z@he#<@oE4h@=2Iu{)aTmArv|FHoS8H-(3n$^p z{%1uyE!{X-$B>Kz`u3{{Kc#Y?c3>o5uXNEbpBMWbDAlxG)LqNp7_gzXsA1rRf4MWu zzB&_AOw3ptS~o2?%L&?yKwM=wdmOFVx)+dknvc6TrMTT<##Y#^hd^^_ ET20`wkwDU7M)XFV2m |11{V}xm)>+vge5^n$PiT!&`S?>|I)9nd~ zXd0CRu+j#b(DYh6F?SIIJ}_V_3N-1AfQwDyc0?{NF3tr_A`1cAWzh#KjB3p)Gh9M8 zvzM_o7E@2i$;sbHNkv8w*k7G|xVXB?5Dz1?n*p0h)WM;WRy#fDtOO{rz;t4Ll9BYx zE%>EXw<{-Lc3|V+5Y_jV=CN>_n~pr%dTlLd-5`)>mB)yQ0iD}(W!aZZObTZbLsjY( z#-Bn%qjonh(TO=RabLfSy53(~3&5t7?e0QNpU_+S5dbWH_-Is%lTLZ_ba788gj&3A zSM9Scw^Ff-BuZZMS&KZ3F9U^boi%vdZzU^}Wrp^RUJt?Q_&Xryy@$PE%qCC8*n)g> zmw0ii=ET#BCpbsXlR;}=X_(3eLU vS#E%nUOTpD_`?4;pF4=|E{p zFF%(huO7XQ84Dp{Jv9X=J0fZRiiOAT1(%FZx5ggaAEXo6WolTRO +lB(Lz+w?JEzx8Z862_KG-f N)j^!u+mUK2o7=nVeT7CB+o?TZpYX-g z&BdkL5%n5+K2l*KHx)!pC7mspG=09mpi7^*ORruoN^d@#fyjTk8d=EyVMgHQ03M8x z1_Co9V;(Coqb*uxHfFQf3Oj`%1j~JTc+|&WQZ-VORXXYN>T;<)$Vkw_#p0A7Joe^z z5fM5mZ>~8S!3i)%+St60H%al0jKu!-?VAJL1EaIvL*50(+u#-Y(p%WIoXEo5=CPqv zHrxp(DSpPcPcu4v^ePD}QHz2K1-H{*XIa`QEMzlI_C5*X bVf0X?~YHIk+7t1JIBV&xK{b&hcQXH@+hlgK{Sf4+CzKUve z*sKVN#%bQ-ay@$4e7(n0cT-d||D)D+W%WuaTl%YGGBr$AR|2~wjR}U5E^9&T55)vn zkIN$?ZMjz9mtrI@1xq&oH(&VyyV_#vx!)Ynvf-wBo)HWtalM%NCA|QgK$fOVQls0> z!4&NS!?ZJ9B{eRe!tI!kns3q{M{Xh&$qHW!G^@-z>?s|VfGWUo81cd& <@>n$Z(8+smhxUJl&|F8lb;8!iQSeA}9T>`&E4kr8TH`eKuh8;1=Q$mOKAo zg=HjwM#u`SLa>^x1!A+s`Fcll|Dd40vq}b5p7`mRnVD@3kwN4f&+IkUk@#?~B9X3d z&BSS#iQ#k)Bn0n=_ZV?OD}CX93Nx;ZW_4kreEXm6I_)Z&QJ`iAc9jIxkX;FD!LG8z z;SV=Y9TG4D2eI2_rt>hT${tOTlT~wcz2&kz$Fwxhwv^`L%1JgBT^b9I 40_k z?Ayr}Lx&J^_Gu)UdJ2oI*6Q=|7KLkgQT<)Hu{I%V!M6bCgY{R<)R+&Cg2TQ(nEcx0 ziKeDzU+FJms_)+y<0MV+h1)0svR;UXb|<(>?>66_X%c8DKC BeG$(h`PJy{@RkiMcW~k%4IcDhEbWKuLYb|1tI|I~6U(37G4XdoH595)V~=4p{3_ zbqvcI*W-0Nb`Heh?C#fk*#sl31!@?U8$h%c)5bYgBm4I4*S-%k%GoP*8!3@XrKDS_ z!p7WAfjhHx*aEjFk;-I^WPEPQF+b7_rHzD8(+TE)_tYywc8gq1IIhU}k46bomTE`- zX%jxe&dAxnFCKD1f26-{>y1hmdG0ndjw4@Jy8a?7>oyNrQ4p;}&@j>av{^?p*7~7O zL8pbHll}APiCjE-JkB|aiNfEjC U&qmnn=#)VYJWQ7pSm3}_X^B*x(7sPmnk7y$cWm2 zUv`7boPSo~Mn;A~a>g=Q%JHyWw??51uWuCV>9dC^qPPr5bVr&`1yCZ}1s?ceVq^P( z;Gz~2R_m^M-N792{fgjMXH_8er) -y*&c83^1*KqF0)}yvx6eC>O+7UtBrW28D1#}sun+3;@?W&FH$eZz^w;;# zKuE*#6>X} -+vjZ9v**w{fmi*8wKHEeJFpA0@?*1{{|gPB{$UI?#x6Yb@LKIa0yo zkzIS3sy?b>6Cp~k>c!=%!qRw5GLhU#q@82ms-^eKH`Au>6xCKxLU2ToSgqPd&E(T` zXXd`9+>K>!zNbRjnO>ABBeCw}z|ZBPa}x^SWXCA25NLd^`1TQvLOKTBfd2j6ZTTqt zKwwsVCywHlls*^>dI|IySuBJcR!N!Oo-o{AHy4HKO>R^NH=CIe 6qO*b3or2 z%GnRs9);RsPQ>#ulcln=#!>q@#H9{eKIHhlnA&-}IpjAJ9-9W?M5ElAxsiz6>l0yS zBo6gKx*dsg9oN-v51SoRJ0rd9iS;5i)FQWl=SO*jRK0u71rjh+s &b#^g4}HGr*%N-`irAgXzPsm+J5uRreS`_S9|piC-_9a8&u% z4@?!nf<*K2@l|Xo5lQ)0ER}utsZ-8VoSKH(W)Ljc+D`Q)410}OnB-f_bah{F{$l!W zGxbe<0X!?J5)LDJ+bs7ah6QM{I z;rlIEzA;FviBr`7T~Xs+#S7|rydP6j>M{1+Xvm5U4!=J>*!BdbDIdoPOXsWenhX+i z5hYkXF#*mJ9J4GbMuiXV7*0UJFJWWD2rL5~rN%bFQo33YGwRmb2<>5yxnvVGm6etK z0&~sja;f|nY -J}3C~p)Z)?05}+Ji8SAHPFCcE&oS_^8SQa0oBVuF z(NWIZ9WURy6t_IuADCEdSbKHT{%wiO76}&1x#DCfsA*+CJ;Ehqn1{ciX?ZVQLR!4} z`n2L__s#EXpDSw_F^t0-_uvh=vrj{!@)q1TnInsM(a%qjn*y#fGY*AjzMAqIC8}j> zPl(W#@PQ6#HCfm@7N?MA#YH+D4C_O+n2aJx29(oEK@1iL)jE};L|?BN=ELd%t!^`z zqog&T%QjZ@I3m=pz5%3_A^N66^H{HoB6IJXdCO;arG)+hg+YsQiRl-8R`_?-MD)bu zbk-cqa`*IR)0*qL5yJw 6;O%{(`i<3Y6y z4{T%FeG!mzwY&b5QR(6exDWO+KRNL@A?CCZ46MOnB(j=_3jz}Fo{%i5*j_KH?g^2h zkS)rQ;~awitAsISJ3kPy?XxyA8BT?aq&C+-107DU)9i;pj#H^?;2yAH5kWyg(PQYc zHA?-L@t&()x5D$xZE!LOf;#z()5p?`HaXc5##yk928?P{OctA{A2+9SERlH;`F?fA zs%66!(i|yAt!z!(bhz-J@5GR;ICMG|`q8G|Jm!GeToxag;K$zXe(ZRHX}RWhm1>Ny z_jx!*irmHv?bBNc`5QjY5-H(JA6%D`Q^v+Ii!UdcPA?QJTip&PT`w$~P=*fPEB~&6 zrFdPN=5}9Yv*7Z$*`Ur{jk))lLE^UniM;)rM~%WIeFu}OCk$Z<+mRSej#m`#GrDA- z>1n?5Fc?{qA>`dN3QWlk9mos%3TrS!%!v0L_$y+$WUlFrR_+FvReLJT>BE?DqlsI_ z>gTSoKLN!;TFQjl=s9W775~a`tMf-2gOqUwvnzGurY_UD#uHV|4RZAvRC59~2Ae0% z<)p76RmGwxe-KGOHY6aS;9XH~y#ndj@hw0N2P+W*y@bsUEBqQ(hK4Upc#$BGUd$M) z9}+AkJsA8Kf{-5$BmBtHdFaQxGc{{6o5*0^IVmY=m0br2{5|e(&+W*1&gb3bAcdV2 z%phEjxo2~Cfa5(hj)XV?% je99+CW_wX1M1{mFafU5VxQ2CH-hCC3g70 zR!l3roI_90wM@U9x@z{G%#_BpZv2(TL5PYLFcg!>toQEJ$RdrRQ^Tqi9v|Ns ^?@OTPOoc>LS_K 6;bC+0gs%9k~04nPN0H`20 zaGF9APU6BI0P2SlF4JlE;>x%5>|Xu(XFcCNX)DS~hv6kX)$;Sn>@6=aE%gFV(JW@Y zNt oE7RE51X&3L7OXN$Il&^aGQ E-()OzfWku47jC1@g?z9$(!KR ~S#e>s4-6k+`lX$6 zEA+m Ng$FLJsdw=>aZxu4P_{CUsyGE#l67eDk z<9HzSPb|cUgtZ@ *RX M_YPw0J#7{|KJ&c&rZA&e4jnpPS`nj;vw zMTo6D5i2a4P$VrxJ3yMP-i^abH1sn28!C?fFPUAcT6TY{K#ALJcwmUam>oY{NpkC@ z=wgZga-q&%f?u{OIP7{{ 4=4{hPZw;buL|1ox|^MH;L6kUH&ly6YSYj z1C`!5F+>7nSBc@iOQ?n)g+UXjD<+(2OeMSeg!s4f(biZ&`8-?nwOXxBy4AoAbY~ry zJwfK@=j$mnHmlN4e^;g7y}e5QVWZR)@=&J)GrL0iS48w#+ Ndvm3j}Or5(DNIl zDX4P!nGyT=R-UyRNM-3wQtqJ7e_%owy4eWO@M6(pqk|N`4)05R%w58ZSm1hn5H{w5 z!>}L9L3koKq0Y02C(F?|0vYvmhCw%{UoxpdEN}ctBm-Ftv5JIxoe8PWaDJ+$s5Y#) zN%CkM==Utuae7KtMHa@9i2ifNU?z<6Ww&1Zk7YA>kyX2+*NGoC>n{-8to%>|Pa(+e zFXu&SC~^*)Mu_WV% VuJ&*tCupv4G+vRy
7?n4xAcN!+m@mT#0)CJxQ0GG3 zNtzv#&~gSQpl)Zd9<#QE)t=k>xm>)$Koj|-tHY@s_hzT+(VE%C=UW@0c$yTKGTASt z0+8KxG9jPM5eeRn*%S7xNj$?QY5dAq`1Ow}1dJGBBsoI4Yus>-OR#IEV|?U zA9y^_rX%KkWLJct>RQCya*srEJ}+(ZGQlNN=Ix%~k6E{@h(KL5F*5S+XLt09BP(Wf zCI{j2n(7p V`wI*ofcz%y pdhx<0x`!TAKeIQE-p;g{ayd}cOGgB3Uxh4} zDPMGaZ`ZX5k^FEWmeXsb^VRua!DoOA&Uimp`DVtPr1#ySs2|gCxu@Rq_n&SeyPjMA zMmxM=75KdIBE`Dwi2h>QiDqX)=L>nI`%mqg BWe3e50*yjmpNMg1K$D#{zCbOLE8YIO)EfN|S=O2d&2n%c}HymD0kAS(|v}fIi@@ zh*(6UXT^u(s2!9R-i6P4kQ$tgLyw^oewH~Nf+CDxFB=v(7V2WFKlzFQo!#E4)oH%i zV*0n&G!9(RfaBfDFb$cLx2RJ^Yq9a9Sh~!C&dt0bE^C$J#y|QnoF}G%EYV0<``boy z#`z>Nr_n8d!c@;mh#8T&MYT5W{sW?41W@Z0uL%&H0kk4;w0G;2Arlej;9<%47LwSa z77;km$X6bAJpHm!s|2rC`BeOLz5r?pB^=$aK^=o%Pq)Bz=GAN`1H&A>U+Rv37*Z(= zqjk{KE}uf0pe`52tfb{nz3YH@0hyjkWlAJ4+uMy!^jJYtzGh$1W6Cy8>&&s{@BqCo z80OFe9)O_Zj1}fkI`Xre#{K84r1i4ZC5v3xYx!=zALm*;{jl&8>1T)_{V7Y%2Tdau zQH7hq$T}=gs~reu5%*((`omOHLyI)EE(zl8dr08wqqwFFMTNW}x2U@bk})@ipyPy* zgV5TrEs-CqWmmcFZ&>l0AEQBvM0feyF6#RpmCZgDXc)lVUI^5@u)JArQqw$ECr-R~ zBzQ4xExMv_ei%9D5=8| |0sDpPP^ zgQ`qcElgBOrD@uYn3;0&_0$<2zW8%JuYyy?QG23rxA|pZOjc|<2rYne+p89O1@VWa z$u&giC>X6w7mP_i1AOVx2c;s~jntizQG8|B>u2pqP~IS+RB?0xI>`OgbV7RA !G- zsg|uRLIv`T8AM(?{7 k(#L+-q z@F|bxJ9P7V=8)Qe%@1l>h7|itpJ=LA)2b(${_L3?8Mn1Eo3zu;3FWws*Tr9|zUk)v zju@ i5HZxO3Tui&+fPpG8xj_U)Y3 z^|%G}uvaRqA`h%Wd^dSnbaqtn>jx*18^ju*b{16gAExp4*|#IC06AoI%yzR?r8cPM z)uK+uN?41!OBs+p5^7rcq~v-dIWW^g#aVfe05vuYZ;`~2Xbj0p@OLliMXeYa>rM@( zC8dAbNRsGe36F_uYf|nzT-xn5pSm;^#C}V_Ms>XbZJw9b^Am2HlCCvFdm}6Q9Ns0g z-Fx-R-wO>_n)i5lzvC^{@i&l0s5?u|>cv|jemCcLVCo9va;%o8L~-zdnQJduCbMOl z82xoC^7C(jWWb~Rcxkruyg@e5`nl>?=D1$&2 0 jOqGi2yPhV}> zD=+LmUasZU?bE$(xKMBW_*$oc%>Pv;d%M-xhnv+hd16Y58&fv8B8g)0i8`Le$~|7< zfEJhj$eEiC+b4y77$DOlI*N<-60DHbY(*Hq7;iJ{A?LJihKne2mWk<>5A1tyAghvI zo(_<5 RR2$8X{-u||k z@x&vK{pBb%%KN63_#_u@U38HnLX7Gx; Lrw3-kmT_kf9J|s@x%HSV@b>(yMaya34;v L9tVm5Hf{O`b>%lGB1TW{eyJ-P;YvVte6qmCiJh z9E3@U+}hewy-vBOEJ8|KtEIE~9^aQyBu9T5JAfAZRwcJ^LJ1$J0AS5&^v+2A9^mO8 z>aq%UE?d0atBn+hInjq4@fIsCX*_CXeRS2z8=oPF&JO%)!Q3<{#HW1~`xzzt7u8|y zlAKb4TT;x%QC!Kz?}Gaef&6YA+*4l0?$Sjy0dDHga6b%5VMJ?IT~Qb>E_`MBx1Ls- z+^{{%!K2~wRf?`H37Ub`i>+X8Q~DiPma4-LX S@#&WPQ6X~sI z&x6hlF4fplfdLE?F==9P_uBlDb0w^Odx|NSL6KIM<*{Sb?GTYsflGSFV)PNIcJtSo zDkH`xKaW34e`O2LD?V 9Uyf7L)K*?t>ytcgy&wx)Gf(*pWHX+7?xEC!Db~!Zd>DkDXSKYFw#Q z$KazIb21Ai@i59tygnNwmJwV;O8VZcgpyfyrftve9)!t=G?m$w-#NSk-WVS(3Xo%Z zKBC5Q>3QLUqs@Vw6dnWraajLE+#!_|DM$=yvHmD3sSXUg+_raoCX0S9Eu!bZ{n6pq ze#8t+vaiF}Cw>Jc7O&hybDj&LCc!Z2-S*@*9N_uAekNYY#w&zb1V#=jsm~wGw(9Iuh{!c z%!9R3vTAb)whhzgpKd-7W;k6zsFSeDq_{)>R;A-GvujIssS;TWS8NhW(l-UFzMB(l zkDHk^!(qh()ifztDUvB84PjP++fsDBkm;m5R-rM)4*_0+wcD89ay;+J2$4kn0;sKU zE|{ZpN-kHKk1QPd$;hQy*G`+zwiA56%}l&2ZXIQ$Of5PN>2EtKBZRddwiE{%Lu-7* z{wAo|Pi_K6_n?K&iSbB<8!|lQ<5ZNOte~}3VdO9F^7u5Q-o?f+lDFI8(@jr*m<>8z zh|Ufsr0?J*em0JD7CvquNh#R#1DO5?$Bl6{VLuMd`7He`?1j>^0+cwZn-%|~y%A}I z{*i~Y0qXfVJ1U+0wGeK;jr6$-8B+lYIFfAf^p(+~A5@j8#ILqloH6)A$sA$raa*QJ zHENM`H1~gaCr%n$K<<#$s7(yO(5WRj)e?Q`*9VHX^B1+JFzPv6H9qPD^pVS)>Q5fr z0R(8HVJm7MxkQL%wh~PHxc0wtNX5eF>Ofkm-a>8U(Dv1xq(k_GE%3&h{8Nu82KlYW zEM)6D%BL3mmySUJE4S?Js~ijrquClvuovZhYLy9?@DX9Li*n?3_;GH(2Q$J87#4S* z`gI^agW1jg6!Ifx`%xOB25)gJ{gYy%lBL`6jQ#0RXQu^oHiXl_fFFh GB#&*4tbJv+r&Yw^p#-u6Zw%s@tjQ*mz`)tgU$2 za-9wY@ju;64${dEZLwaYPwS0C__zK#`^#5cMuuj{z!Uvac2jTz!9dTaal`?ukrzi` zcynCw3#@&enNBVqD@Ji&c!sJ6 rVtp3MrP%?6}{IX65uNKmH7A`JnnyI5An zR_j3dPKR9eihhl04YOXgdM!%$Hp8-Wi5T=|mSmrOH)MU~`659ALP@E4DQ;IzkH4Bj zQUeBQ`ovNt(_?`;hE^7pIfV{y`a-|+Hhc46b=czq$J=3>3%A-J9VT_s_CFY^*X?wP z8L1zmy%BERS8CXH$5?IP4dbJ@k{=OU_415F$@C&~q)f}g&*&izLM};Q`_yx5 b7}v#g3&uWWNTr~nAk9G;x_2abJkt^M zULD1gi1`hwX)K!Rdz+%mk>NDbFe@U1L{OnDH$8=4s$G70llM;6;?>T(WQq8E9hW*; z7;fqCk6r8L(@>3*50c*LIknF`=N&)ZIOY4-Zr-jj!51&XZBXjKyUpsNiW=V1j!wX> zwGN5U^ry7@? ^o@JQ^uAVMT>?;Y=CWB?b&Y1U%~KevcPmutz3>h^==ptt$>vpc6}%h zQ62>k3JNMCd)cN0Jn`nqd{5!bt2#n9G?DQ**!M`>!J3WeQ4M(C>=D {0ORL3wqs$NdPLh-4qHw xS>~SCbjRK=tZVz9d)#&m544vG3aq-HO>t_mSDqYgQ&n+3PQc Lih~BOYqT5X5rhFc3+;Sn~WA=mnUkQe9>k6Ne3L2%>*)3F9^_~}yNUA!t z*HlLizjwf|ADBUlpqtQZx}lx7X2VG!t6$p9hF@%4C+7WmoDZ5Mk~bfMjz~xJoAf9f zGxoZ#t*Vln(H0zt!c6WQBfGwxmCbtdUyRwqau3d+oYSc;J+VU*sOxWI!A(|}ihx_c zoq}6m@Qm%1zeXxh*kpI+;T2nG{w&x>&~RWp;sw322z%gwtfg^4Yi@P*r&a|;rq BlqmOrWqqweGz_;8NQ33MC} zU@=Z)XKe5dixX2$uq|JRzG|oBRrd-xwO(X)ofs$)6L4w^T0=XxP)%le6vwd!=z(^l z)J=z*r3TT#`r;iPrSV*9r78HZpd!Bp{BG9k3n6%8l`j^O?a!v7)^!l5^olbu;> b#9f>uFsxWp|;_K-CVbelebYyh_FS+4BIcDeIQ((m)$IF3%&s z{nv^q3pYX-gcfhRNU$Q^9BQ@-sU*YuXvKoPSa!(l@snSZftxngIpGOn$-p$x &OH&@V7lj+U-=@BJ(6VEny&lS#`w0#tCh`Q^#`{+32nBJYii>9&p@8~=kICqH zRyL<^K5RDXR!LAtn*8&QyM#N7t|`AaJQp=@GF aC6c!HTV# C&`#!1H+UFWO8eJruai2nBK3eH7+&zB1t?*2D|1;g8bH?;zNLjo0!vc^c4xr9$E z6M`pGrrnaP1kLE6!6$l6{k2rx4WIODkIihHf3=d~ut7gW4Ux=eVmzv_u!rIVGX1$Z z5lz?6>e#tWX$PLpIpmFa7Z;DbH`H!)zXhR)(!b5>l-i~9drwz%-IKiT80A0kR=^^) z6!_yaIP2ITFih-+ncN?X4)|P_YL?>hr*mN8)6uJq%AyJ?3Ur@(M>cg_k=2lescxS} z`PCmDgdMd|H_qi!)(>X!xS6387r?DMt+c<-m9C0`U+G}Nir~N}AisD28A}rQNvJ_- zToagw?_fC*F$C{=Kn>Dr)vSJcH^ufblj%AU!csC_Y(l&-KrwiAz{#MZUtYGZ1Ji8* zfQ~+NloYwE&bIb-XHP(s`@gP; M3W3WpIF0Q;3X OfT(jBkI`-D}g+P6oUQUle!$=0GqVTjP zk|&H6PHsfqvuxuJux=YZdDiHZ;%R4hW!(BRRuZ)!lDrDYEZCf|U3*I)dfj2vZPBaW zVM{ BY4C6be$A&biq2Vx>-FGt+N%u5UFLb02QG95ic@&X#LkKCg(f#QmPv zE@mxo`%UhUko<}MxVqg}*rv= +`pgn5|owSU6gH}>JHCua9RPp9v% z(i$G&L;9`RwkYUfz8-}qv!c}R%cf}_ylqr0!DIF2N&nWx3MlUvNR4%{75rLf*b!C9 zO}b~t5nT=r@znHRLNHcN#hVT-*vJl@c^h9ul2PfgqkcL5#VP&n!=9KA#O(|iqxv~S zwoG|M3jC>;9yED@uCuGPJ*hf}&UHo;!{kfsvftqcS)QloF<~Y^+P`R`87J`V++o5Q zf4e$FX+hinLUb_gK_^wul?q_Ug~YrVbo^vz8=uOASt6%hqVjYy4&fXvcJ)5+Jma2= zRE*p@8`Yos&DrCLJB-U#wX*#~15a{3@q4Kh(#T!3-a$;Ef?HUq`TNAH7zm1I`G7+cwO{zVg;e9@!x>UdPT+6>WLm+~VV+lJNS)fdS+2n~p zQ-_yZ;O7;bue6kOSD!c5o7lu|Jf&_LQCcqguj9X7%<)_mqb2~VG_bEz%4W_3k< R-N{Ok17BXX__^krJ>61D_35%usB&}~Jzxs~;G z$?vvl7P&N9uYd;5G}Xsv>cBvd<;!bGk??2G=_tE?;}B2yn*Qa)T7YCV7JN?>j_mz! zl2E*Dgbb&lfTP6c^|_Vt2~^hO=ZWp2oU}aT5R3dqm`(U~@IQLgdzHy9 $ zQQzhp)-`rAtjb~xW$TYDcgOHGXo4ZXeQCe`W?H?^tSZ6?WUY6rcy! 52=J09U`U+e5Gp;V Hr|J_ zUBH;j*Ow#pZk`o{x`Y#!B|osDzdwZ?ptg|T&-j{^CMvQ`%H$EAbSAiCF%lpAhZtOX zzuV#9L1u?dXAo&rn&gGS*d1N5=)={JpT;RbXe_p#Kqty>^ie~_DJnJ}wI?c{wnyHm zSaj>?rP9 DF;!moE}KW}$|j>z0;$Ss87ZJo4+ur&_bIZ!o<6!*BX<-?Z5 z8uNRPe;^Kyb{-!T93K)Ne{Dj+v$QMDr&py%=8?JAds=RFL>W^<-2Ai}v^dQ6=o=>* zQ&GL|Pm_^MY?n?#-u4l0x+3-m!s~e33xJF9c2z-N?xJzTrnXRkG9 k=b_H>D5n+&3t_-YDw4%+nA_=! {5wCSP_ zoi3=TO{(f9{c;9tAkg}wNjKZ@P}B7v!jyww`l-P=dc$V`wiK%KDJ9=Ih~!K)0B@cX zayu*7iY2{Rj`Kv|LbGs@z5RxDvjRp2sYLV`Ya8mZ>ULRSm8ut2xEQ>Vf1P%`V|fr< zpGkZ`qvAIgl`mvnSceC@BJ^LHP}a1%+^n-4@Wu -?~Xf}jZP>87bmX|&3eL1yOY4~_#V3bmU3y!wmI)=N)s4*w^;1olQNjK5uDOPoS z6`8JvT;M=(#nFC?M+~?^%bQzPH0bRTm`O*VHy>G zVT{@pNq)s=%24T>maH>k5f0TA&aSRG6yB+?isK^l86X&}c-Rqi(t)r+c8_%C=iN3c zj`s)&zrZ##DFsb!hTEctLka=XH7@01 YGhfpr}?8ZG&7tFy|1Jv7*M z`MqIBihsw2{Ql@}(W=g=Z|V7hQ #)ANnmGi8#%q=DWs^&eyp+TG~{(% zrn1oxt(3Au&^iZ?@_{a-Yi#2H$S_^1tS~^A4&h7+y^T_sSKx5= $iF> zH&l&=qC`xO?3Mn+j*GxQ5WRF=3+CUGzHu2cpmP^ZplH>pnN9O@up}Rbiy<0R!;j5W zrWADYnO`d9AH5VA7>ItOQvF>O_f^3v=rq!OgtZTcEn#GQg-uEn3AGY_=~YVTXLs+~ zd-U{5qtlxGcSye1@vxB@D`EJf$hO0p<>d({=|{8U$+5tHk#zP>!THcAw#@F O8H*m%(PVaxY^sx 87sIh&ui*;k6oLT&48J iF286@&MT)aFqY 6D|$U2#OKNya}X`QhIjTnC#s#~7?TByr2GbyF*(!=YkVAYU?txSD<``fnZ zP?)LJuIUl9a81jYJ~F?pSdncrjO`pwFdx#a^B)r5G!r?F2 GH>O?q^>7H@H15fxzk>3t<&F*@Tn5X_+n{qsFyatTK-71*HmN?e;^xPDSu zW@#HBgn}~T;isRc5ni}`@B!9V59{#PKQSWoI5I62tEkvs;+{!_s{9=)1{H#D)GF%V z(jO{z8l_+6#4i)S0gm%`BtBzEn_*tQuO;|PiS6~ZF2vWvaKn;Eb5P2MG?gK`{x_`$ zvj?#0y;~R04z1Br;g2FyiC55}VR;!1-sykkEfv>q>77F5lI=F};HUJl9>>|EUd`h8 zbv;pm=Ml( -c;Ns+N4a%tqz)H=X}Z zkCCVk^@2+LH=TCOsi@As`2FXYAORfIQ9~jq@*$31%4jEz%IF@39Wd_D5FfL&KdVN! z83KdUFGml2?Z~edU6l_s5oG4bsm4t?`^qiSm6W`x=6~}(_Vin^J-o7%KKb>z <5^9%;Np6hW!LFdzM%6pxr**X42yV2z|AYq@r+r|)yH_pW56wq)+ zH2i~3^=Z>f5&L^*yQ4rU)f;$JK*P~1WfcD2LReO%?(ZZ}{?hPI63G5O!Klfc^*1^L zV%V8_pE`Z=NB{F3{J6n)aMPhdYECz>$pfo3tBmIK=feZKP8nXe wV?o_C z|7@bU7%(gWa|wP>rwi`?SsBp3I?kbC`Rh6Ue-58n5<}kKTDINDCx36cWHJ>$K8|Sk z1vREx(ls%`f1Re4wn5nA$PgMm`k2Jv`})Ch+UwGRdhvgpCnK$ql|Y3M_NPMl_Xb&2 zjwV{mq7ebFEyaAMZzM&d(pC=6CW;0&1vBB(k3L*oX+tthF0=}4xyP9gXUPsq^coT? zIVLy+Zhz)@sA$diz@r?1pv(KPO{U !?&`m7m?y|#G%}GdZ*G80gPm8HX+^82|s*Pyzjg7k?ykpQS!2NQ+rmv#p7H=I5 zS8fM;QS$gTUm9-Hv5C=w!o{@JcNZn i+GPp4vTnJAi}39~&fRChI`yPX_g#3ugi}$ZJ9;{ldW!7pIKU)m znJl4a$x@`^GfoR*9>>hsFox1 WJMd>hX1mQ5-F7Ax`?|U*C zrJJc~VJnz9n2j3O@{iJQa(hFM6ywSBq`UKIczUH&0^duj#Jn%8oBBp0$E+MpM^Jzq zeOiz5KrEnq_*XQX1krHv?`T+1s*MnZ2cwAkMv5LTA6Cw;^=9?k3q30)1h(DljQVy# zE<-T>iX2UJB`1`bMqv8O9zEeKAtJkJBU3#U(RAE7eca1+rjlw#x2zvE5eJSaG1JAX zckPFGL~Ee&G@xe|&>(77o-9SNWJty}R;1(9&&)RrijXReNyobfgx1yP{Hp?Ke_*7r zq~-A_yZ`I!;RJ%%Pw)`?Ri@;<{-B)xuc3bd+Y!!(_f2_U$OYKe-l!8$to)661W-}H z^_71m;(r4Fu_D(&7%uz{C=Zn3=O>9DURPX-9_G6l^r1OkhmX`>QjH(15q_)C{vnrL z>n#40_%ioM<&Z}uJ|^wF1Fgh15EK|+XjGDr6W7U3Ta8|6S!#A$C?QxTV`#>2n^w`0 z`O@`Q*7Y*Q%=AkquIpnfg|jVm8c%P+TABu;Nvqw%7I6&nZYPws{Y1OqvcY0?bg-uR z+iN7Shl7|gvE PkFt=zg1r99+2Wt6ddK(gBdP6d6tsL)A zizQq^vT-qt{` X}9Ef6x(nM3I_FF~=+GbY+PHwqi z(byh^O=hFlK>a#6LLbmQ7{k4LI76N4 fLbb#D4r79gAh6V`+mCAg?C&0u+d^ zMWX`G$MFXg!dhE|qrgx@41{!GZq8xu!M+uJ*tcA$j@p5LB)+I|!N#8JnN=>C!}|TN z2xy!Wu_za8Ci`a)XIvYANDyP^=}y4y56@RsuisB=Y(4L*qSh-qP9HNYZ3u8;87a=z zN*bZBo2>KMdEdLZ GCXakUX?wYn>&HwKDt_V}}1 z$Kb!wSe!>YY=!IpSJwR&>WMQ2D#zSHRkFWYQu(kI_`EUsgp=TJ(>0Iy0-&!`DhBW& zACNDMBHKgx+6d%w0(C&O=4REdFyRjOU}*v7AJgW#PwlG9!Q2$Hv=b^nYK~FYV&e^` z*1IIk6#wmBB}r}M_`#TZ8gFjgwD8N(He%I+DsR#0`1B&`iPh0p7)1k68jOZSJ4>gA zHT?;=(vY(4@|h`Vp7>HjdZ+I8v+aQjZBnOckEghu!5m-M9LfCuK@&Y35iI{IWOPCD zwEDY{`4=PMsXX;0@9*!b@#+8hu5JJOyZ#0C$66-}2oE|Rf{_6+W6QW1=aze@sAuY1 z(`j>h4Giti;VZ)WY%j3D HKJ?iUNd!lD*I?zfSPrL^LfdiP1`PnpY+CK$)Q zoZ|I*^&%;Lhids8B(|3g;jWu{*=Me%Id)P`mdDUe>7rw3? Kw3&Vlx}H|5a|{Kk#3|B zL_$Iu1VmA~yGu&oP>OVScb9h`@TvDc@Aut11`dTE4$j^y=A3KowP5*?ONNU_JpXTD zcjI$coGeVk=eXAJwPe9(MYy(MwVzEDY9Ki(+_)=BJ!%$m4Wl~3l$Il?BU|jOs{`+a zftSZfP%L4YPoI7fK3K05oBCD=p0JPfj-qAK1)5fER9|s{R-FLbZ&)X9rU<9}49y*| zy)Y6*;)vr!>nU691_C3?pepRDW!xI0N|~82_0lz8>nMK;)aoP4&NslJnQWWSaJv6Q zGd9gOmd$O&>Wz}yN*3352Xbh?2+k&ESXXv_;@G{iUWwd^iT9yfW@D^4wdnctPgI=8 z*#2;7bl(mL2eTv1llFhWxGvz*C4ahfJ5wng7iVpbP^Stk9l>g^WY>o7i4Je}vkCa~ zANQ^mu?OJyPCFBdC?oPmI)LbWdE<};V3?uHchvI19ppz6``&LC!Y)_nz0@p6O;7D# z7S!INwD j9nd zu#_)2lg#XTH>!OwOM7NVxE{@xhO;)VP{x^_ndqJs+MDe`QInW$Nl}v(+F9U8A&{7D zLLoqWCrRJqe);`R))Zq4Y0k-RI*U(TQ!2*q?@Wi*_Yd~#Xa3E7XkY;Sng{U2z}&}x z$&uECU=SST1c;8+* 9a3!pOU )m0#J$?*4jnZO|W 1o~$iT+K*Bat#6n`gT&p3K4P1ihLYJ`;L(U#Qp>U>a+*aWmYtTPI4RTH zBX>~ukeI}a1pUoa4;sh59kpE*bqKN|e?IDGEz+mEQVgoYnqGNu5^{79?KiXLFR`Pi zC~EFKQ1IkJ8KrL8g>Nk^#P@OxV`s`8MI^0W*-EM2(6&88ENodp>07r+J|N@`(pRJ#_F#3}^xSCgpnHxm!Z>N&E9*I--=GK}H<%FvV{L z{v=~b{cJeEujvPb@*M}d#A@}$%C*n`NVbeX5aP-ISE#LJS|LeqrWwmXk^@ej8#6jg z{pRV2^<(q|kc)sH|F&Hi$NPuvrry}DhUmy|KMt#Fw?J5eYc>}(BdAf1@NY@;x6^gL zGesIbL*#<-z>;6Kp;I<~IDvvQQ5zY;g}} ^-Zl^E ztxWaj3sBR>Dvu&v4-(r4w+pMaG7lQJ_=iESnerG;VE5VnPPkHlt)3ar<=pnCA9DmR zvu%`3Dd}3Th={yAEqO_7lGxsge4nAISf?4Ht6$ArX;HD=_Xl% z*!=pa+B`n6VjTJdBpBAx5oyUd=_J8uR z8(wVmH$GNZ95D~y1S3SNzHZ1m*m`O870{r-mNbNttCHgk=DD$`yp(z}Yh1P;q*y5j z8J{^w%(LwyWY7~*vzPpjla3{FpECEG%73XU==jt n5-B;UYW-cTj zl!B<{9TZlSwBnQF&y!VQE3`wa_bN1fb}T$Cg|Qdwmz!Kx#kJS`;7vidu=`BOBE7dm z68rf{SqsMlk`lcm&?iMK@F-ZU$Gdws>?fZZwhm$~L}r%6S*C!w(0(p6kk2)_V#3el zn<8IGgC5Pcg~ap8`GZ=^R(-y}$v2u-$U^4r&MT~ZK}Xo&!F>fc($sF^+*l??RGY}- zcN=${HAQUL&zx{KQ(7Bpe}q0CpjW8L2u|%y!|@nsS1KzXcR)~zbS**ZqP^V2jl-1L zeKW?*h7g_>mTzv$9yc(}Wu;VCs7q1vK3jo8fV7siR>^F|{9&L_S)WAhrkiC_Adj>_ zkdIGJ5C0!ivLC@U!IkR#28vp{Br@r+3_E{uk2lPbHnz(um@qXFolEyF);^s{>?~I& z+`dFn7UFMAteXSKXu87;AfrQ{>p+sND_+9%uFru9Uo&Ccuu76>bpip0Zck9){G7iX z(eUk5MNQ{LPSt@HD!nbn0=O@0clP+y4RRfxgkD}`)$nNNw2XD%)9pb44_V$;nDBfB z-2yLP>qS2;SwF)#;k`%vey{hW;QSsRi!l5#>+tU5^T+qDB0!U9uUM@;brC_gJ}+If ze%>;PJNZ^p^i0_rVe(M2f8P*c)$56-+Wa?NqrK`EW}jQWsEicyArJRx&fI3IfVk*i zc#~k~DmOpo^&j1FzfE-&S*hbjQOLa(2rN!T*qlN@DeU!RPIQ{>nuOJpgV~bRsEw8v zEmAMrzH~aT-Z86ZLu))`m00x={&-p}81ic|NV!%?@?5H8mbrktA P(OHx*_RTWsWc2ANi6`q=+*t?YeQMsb^9X@3scxjeS?O10=F8<0Ldy09jZ+_a zMb?CFJ4=eDI;Gz0_N~)vBoYYTbPM4*$dI|Vj!)OtAq=cz4OoXBuns|cA?N@Pj&-Qh z2!>j!;~%fBVBrB7+SR9 @Jkt91Ktmbg?J1*-Jya^NDz;_cX0d1lQN&qlQ(xp9LPmIpfbgcDZ5GYh-FFm zSem 3-pQw`{?adt`j;D7Un0d1QyuCJs1k` zevrgRk0mm&x|5#RJ;w<~{|H*u`SsO=%OuL%WUUAjq%3Xt>Vhtb)nTG8Rbu1XDYboV zt6?9({uiq+NNj#UpTE!6S2}_E7#RN|-!Y56GQa cUm5*Ziu}5l{YVJ$%{n ;LPK99h(|N%@r%q!rgZMly zr-p4&)2r#iWq!(Bz=}05?t|}-c1yc4C-Ot-wvR8RG)a<&);KBkpVNIC?I{lo{49w? zM0oxKkFt#7^&JG>7MDXLzPHXocelE}6LOi~zWm_~^{`~h!5+EQGaY_!w~|1_MijGL zlCol*t@%Z%76X%%M-RcgfwTVSMVqIcC(K5Pm`)18); ^sP6Kl!!&Dy_3-C3+R6W@;~5ZUIzvzg_cCHugF zVAj*8@lsl7y3zCY$L@=i6&`j9b^oRLQ452Y*#@|G6hmTPIi(aA-#bsmxf*sR(@_kU z3|x&g7q-W^!b*sEkD&Sa++lZ#k6sG7ow9-yt!LZiq}h#LN113m6~a0+>X(|F@zKfD zH70lKZN`1qZqQV0f Yd$Y_PX#FrVptj#zgG?akvKT|oPxqnpD_{j;qx} %)z9?6@Gqv|1YdaK2A-$vl~I zF#~9o8i}ltbNflvFi8lM!h7Q|)!%e~Imv4Q%1KGlzbGepe<&w^bNt*pC$KbO*OYgY z1Aqmbm&Y$Y(nr_jZX6Zge;byZ&&;|_YkTV?a~!kmPBHQjsQ!aDT%LEgXK?yX_so1B zFeg4Vv@pC-mbplsbaKKLVO(chFEoV%6&VV50#U)fm{&}(!ylVszfPzw>hJh>>pAIq zBO4Inzb!7Tsdy}Uw9Yp7E03X5mGr^6CK$i4@p+?>;-tqFEl 1$*gFIj&u2C>F8iNu+3>y5Yl)!1kn$Ni$=OFO zBWXmlW(fS;5=vZ_g8%B*x`>X|FeKKUEkI^aagdZU(1H5`R9mmIMxW!o57mj_`C-y; zuLM8V7a}!0bGZ}L;9o;Ppi+<_+EDhvHv{NM#uw6MgqIa5B!NnfbGxRMoO@NjHbjVA zs5Se&E=}uxs@6r~b!67{u?%<<=sX(n(*Q45U+jwTz1H{lc$mSZ!lMR?tZD&W?v!R# zk8&QGN`T;Cp#BbK0i-$TuoWCPTSU;qW$-wdMQsyRJ+VvFem>8>xUOR-(vakyPdv+7 zD^kDM%>rsdQfPWcrcDq*9IQ4oe}?s>Tpw~$s*SJhngg=cS{x&6x6s^ ~9h~gQG3?1?H<5Iu=s!_)E8c9nSY4_NC z^SSFCZketVaRn*+SN=Kry2{BGc9CY|X|kQt{byywm2l)s)`6QDZ|%?<;o`p~W%0cH z%u+1Q%eFy##kyIuL^fqELfkieAWqk~YR>rrqlQfs{+w0LE>!-FrDu)jkIz8Y%<+2` z3!;C&A8LYnGgmfx43>I8*PEQLu%BudGHDGdz&UdNX#}85vYiV=Z?5YUfWY|R>XB*q z?>3)*vNv^81$O`t8AaAt()++LwtdVczcP;hAqMo2z+`>HLXa3h2mk{El-ZE*ICLF8 z2g-cf(}_(o-T;!TGh^d-?hr7-KXTWgw84DJ2M)Zzcne;|Kd$q`n6elo=s_+NJD0<= z)3YZNdF+aZ>#A%}d13q=yyIZ9iYJpCUL7zOrAEX$V{aMOm+5luRyz_)A`zS+O^S2Y z--oPMSu6P|?sz+WXn<_eTS-qgDD1d(JmpI8ZpaW7fKFmeS7AmE^VYz91U-jEI(0-T z88V%T?cDCHtsVI&om9s?^q2i~C#V-~r2b| XT@XZ^ghS+7w!IYqtD*6BNcP=QC@YOlQdDd`&qq#s z1i^{PTcCeV{sX$^gA&*j_MydQMpKk&eKv^Fsw1suP z9&?|EE(hF)c${?X@e6rLU-Ob4i-k>L^uHLO;Ime|ZR^QZTEE(<_&esa23?P9_yQ!O zT$m{!buz)g!p(dB->IOZ1&GS2m5&%jy0voFO4YpozyzwE8eBss_hb3*n8EsgqSW3e zv1fD9)q@r=t@%ftBXwU*FQ2o5I@XvB8LY?U? ;Fp`NvgXDRW*nL~{B!vp;y|#(seZw$90j9kC2E z5_IeUk)OzM$7LS`C@<)fJP^$1M;M>+UlC%xlUh#7;y?Mz9kIov8^S-YJ!E=&eoRz^ zz~Hg#>>URrY)hpUmrl5{6v9_Hx`*+fobtVyXYuH#RPIcyu&<9vbxTq {MI#xji5IoY23Nnij7`lG$;%oO&t4V$11?B+wJ|u<~>~K(OC= z%Ec++cJOT)&EUKwO1=g9 zO%JOSCO^uxzfWR~%+U*m6&Awo(@ETf0Ain^IanW0-oNSWe*r>WT$t8A6Q+LM8zEW^ zo{8txR}dEXYP;okDPGfnu^7X{;p{x$YHi9gl2W{IX63J5CintM$}vx^i+%J4%;fK0 zRAh7=5wf|Wi6G@dmS?gtQV`l+rgy+5;JBYMdQLn=1hdAZ)El+!wCu?YjNRhtj8oK? zXBiD7YI>1^e5x+zx0{*Qum#u!LXUN@q!YWgvIb1x$TU- fS;9Gw(#*PSs%&~mwn zW*Mi oaMCsE!mY#&`2AmMTra&kRXFQ_ye(a>mlo!5E@ba*? zMNC=G0%{rVvUc|_^-7IV Q#;UWm`g*y~n(D~f7>z0@ z18v?OHF0hrTeUU1Rjji&$(N;%b(3ev%&u>Jew>zuk%Os)QCOw+Af-W}SH-(toa#;} zT7W_;>&svfx%d?|&!>W5J`34yN)K^aBA!2Jh?y fbk|&D6tFIjjUO&O$ z9}*tu34w)xF86CR$N?CF8h{8)>*cq9@6yG5VkZRk)joCWj+wjvHa$l~VNvFCnOy-! z0#{2TBehf0SyX bFD|XU*=b_9q=7i;>wUMU(dk&nK1Q!psG?Ijn~D{0?*8n%_UC@^&!1XGzwm z!;Z@Orr>o?6xea&gJ#Q185-roKezo+-Mn*lNhY@8{ZEbACt42ImAiTecGoz&^Mg zu&m t%Ra02wOaH`WwzPo2l#;TN zB8bO?_pA4zT-EC-v9_tXY0hF%Fq=ZG{K|6R#jLoKmffu|`u5Kc`@oBNXTiF(Co{MX zSktvVQq?(IS>H|ItTf0X;Y#~l>=nW4l>GQDnN3dJT`=?R-t=>FzzGS?9TA;nWM;zJ zFI95VFqn|o{94-gi$-6f8ICDM^5S?F9^yXuP=PQxWGLMc`+T>2-il s&@#uWDL`znZmxM~ED-7!a)vLxGf 07Jx1NbC?-RmBHW z e}XX8hvo61HdEsrZ{+)$pcRD0%Rn^?^iTg; zX08TBtS- g|!EINy6F#e_N9ZKnZ_VdVbRjj5%0)Q~f8<$a)X! zCBT+?d!!sc%IS*Ufi@Hvx-7mym*y|?(|oI))Y MPgJPQAz;7+!#b9wck!F0jxC+G?KbABx!5ydmD1sdWhC|3*vt_v z&fQoSTeXO=2_&R*FT5+d8kD4XNlJ#cN@d@)s2zP}Py+jp3iQDS3){L7O1 +^@7516q{oAGXNs=K>gKunomV+M2Lj9>wcwq*Fc{o)_|4Gz@zJkQ zL7bhe5H?I*G2B&sNwK0|M+QyukaubK?xBW!_b9w8za4Zi<*{8)Admn4u57G9)H^ZM zSMQR28b(v>T#u|2cmnvAcfH_iVPnv1pHH~mhq6v4ifq-!)daEQvGT}tL7-ZjP_(7W z8n!5$)0W#LqP-$w+pdQ4B=Rn0!eY3Goh}b<4^O}OkS&;ygQ+8rb(`{YMQvL4QmDV$ zO0Bp<>T2z!dISaGW&HWusROxVel_b6^fUYBr{fe*!=v;%bsstWW+<8|GqwXs(E4$_ z(bDS@hz67H%rh<&hFD0lN(Fqi6=G@d0=Dd&Qi?!i0wte47@YYeTQ%K$cdkwKmhSx7 z;d+_(rF)K6@m(+}mF+6QYP4kFc-lu9OgB#t3PSaGq5Cl$4A1@{L+K?6#&Q~6a8^4k zrnQHW{#fcsV&vlbZZIbK@UDP>j=Z QQ;@g zaeq>jYNMM8eZ!ggIZTgLj;rHR`6R|Z Q>Sfs!x|ulxR#jO^3LtH=|k%e7bMOFtirz7cGzUblZK@wLwq7Tp5^Y`U(7ut zt)G5D??n@yEuuztpV3#x7L{OLBYB>$f+2j&sz(0j8{4$ywM%h+Ca2P$)c1DOZO^jC zg>pC@5WIw)NW4T@-|5(fe+-{XI1)_DnwpSMOKTxyQpwNs?57NOyBL3^mhtOO4tqmu z1^!{hh-cW;dP5AwWeG~`Du3!7HW7Ji*QvDdISlD@Vb_&t@AZ4n(+yWrc;**xlUP?6 zd}i-Jc|1_la?hhJl`%K#zHRx`fl{Wnn)5gG91#a{ZY_7eu^<5*>qe#NM-x(oJmeD9 zOs?^!#Y`8AanY-}#kwoGc)8hURjh+AH<5B0&$uADqHjWmD8ypD4IzzEZw@hVP#B{5 z`Lgq5<*PCIvaJH5yU>+r9qm*{(HUa%iJPtN(!u*(@Bc`v6nh1K0A}+VJBYK_?Z5}0 z!VB+xquHxBsCOTYD3XG$%kTheHqxJ`dTGR=D2rZ}d4jQ@8)Zh#@WAfMEQiCno_!PJ zcU+3;$l4bITOwjOO{BY`8E~veOWI&|H}@@)My<^JvHMcu^A)iE_DEAPf#d01Be@)P z!suxnb8Fp=1r975O*OgGl5;A{D-|O0#kbDp>%u2%!Y3 fxOu}i zN}NNGu3k`b?*u-65E!A8a#66Y6zy%4_?4}hs7Z+4*Y%fzx9oxoXYdUI72E^3SHp~y zY9ql1C)HIAG&1X8at*pThS=!IV=B! @$KdTU;Sly7 zDk$kJZTm4bV Zv_c iBLgbn;QT6gjZ%il3bB!d~~S=+u9CL4GEdy?tLGBtz~p6*sSgV(-Pu`&zYr z6lFzlpm%J(m6M?IaSGaa>vUUjw2SIIBy-VX(Pf+_ySYv@JHs4|yJ5(hEEsp~sGQ^+ zG#|h_GaD2*d#oqZou6i?k&;fCff6E6@#FZ3i)u=zVC(t%>iTT%>iKH(pk8w2<_9f{ zdgeEG3hQO3`%v+nZPVTpRP?(>R}56n^%-IrN^nbxUX?8%mQPU7bxnV|oz${Y`=WMr zTn=u~d{WAS;AO|ELImW-@ FR(g6i=zfbhn zBd|szGx7fOF~jn |R}gMJi*BK8>EjEG(guW(c|Y${&Q}P;e-|AfRB&f|S3}k1VOC7Q^DtDr7TN$EXSS znI&A^v>5#yY>3%C{OD ZL-~MaEVyw#QwJ-&V$OZQyDo5lwoY&60*s%H zKEAbRKlLP2sZ&IJMr7{&ZB`xHbCQpJ#aL(+{EuHbrls~9W}$3~`{-y2eujb%zgW!2 z(DmzZ*bv`2|DONmW3ZElcD>nSWDRi<<~DcB+kCV+*7w ~pj z$jli{;^Xe;#Ox_x2UUkNS7U}69r0$%alBpFg|HP9z{hWF84(!D&}ukf!^8X|>B3jR z6DfX2KyQvYPtF$6aSY24$+5%v>DWlro?jw)?gX`iD7D?Z>cgiUdHSwj)NF*dIk@$m zk_BuamsUj3y~`BNK^Ogd+{x#>+zF1d=u1k1Y1x+ LknlLtE#_SVAjvE zZkOu3e1nP~_RH25^_ 5)}fAIq?Q+hnZGYW8axbnrrTZW_9s7Jjm; zm`s`*Q*7FH{KWsuw=0{kE@$34?>zHk%{2ojU9&dB?=dE=vkN`!88-ZMRBJNV!SijY zJ-1iBdg57+TXhWy&W0t`*j~N40;@e1H-k;)wxpnU@-JTQaomU2F4Gke*7k$aWYcPO zZ>%{Ql1c&_Qi{SXLK<@JpMTU#pHNM%4KsI4YSOZ3SiEytwvg~;G|uky&T*SebLTT` zB_`$z>UcN?@O7Q@zh3`LclJxkSEl$dBc8~KPl)$5aFmmHdal+cef3!NYs&OS>l~Mr zPRC*xpWIW3V>#&Iot7n8R|NYVUQ@WQP+LsZRTIXcp`orn3_yPzfDZX0D^)vqM3z+x zLU&21I$5fSmrg;y_gpZ;mwPhWDxamX(9zKyaKD57O;OBwJ{P+(claG>g|ANLORNCW zNcWYR1XJ~6xeR_H+<9P51%~k_`~1vN-}7wzbyXX)nZq&`EI`#^FJeWMHr0Z@$7#|o zJ8OeghPPJ@rZ&g$JDO?Vb~Y*J+al==6p@ nVN*a8+j