From b99dcf86eebadb53a2d95ccba713be3f996a2ba5 Mon Sep 17 00:00:00 2001 From: Luca Date: Mon, 4 May 2026 19:02:05 +0100 Subject: [PATCH] Better BNS2 calibration --- .github/copilot-instructions.md | 1 + docs/assets/linkedin-banner.png | Bin 44494 -> 0 bytes docs/assets/quantflow-light.svg | 110 -------- docs/assets/quantflow-logo.png | Bin 11919 -> 0 bytes docs/assets/quantflow-repo.png | Bin 54470 -> 0 bytes docs/assets/quantflow-repo.svg | 203 -------------- docs/assets/quantflow.svg | 252 ------------------ docs/examples/vol_surface_bns2_calibration.py | 13 +- docs/index.md | 2 +- docs/tutorials/bns_calibration.md | 52 ++-- docs/tutorials/volatility_surface.md | 23 +- quantflow/options/calibration/base.py | 28 +- quantflow/options/calibration/bns.py | 97 +++---- readme.md | 5 +- 14 files changed, 138 insertions(+), 648 deletions(-) delete mode 100644 docs/assets/linkedin-banner.png delete mode 100644 docs/assets/quantflow-light.svg delete mode 100644 docs/assets/quantflow-logo.png delete mode 100644 docs/assets/quantflow-repo.png delete mode 100644 docs/assets/quantflow-repo.svg delete mode 100644 docs/assets/quantflow.svg diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index a60913ec..7ec3f14e 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -27,6 +27,7 @@ applyTo: '/**' * The documentation for quantflow is available at `https://quantflow.quantmid.com` * Documentation is built using [mkdocs](https://www.mkdocs.org/) and stored in the `docs/` directory. The documentation source files are written in markdown format. +* Split prose into short paragraphs (one idea per paragraph) separated by blank lines. Never write a wall-of-text paragraph that strings together mechanism, rationale, caveats and usage advice. This applies to mkdocs tutorials, theory pages and long docstrings. * Do not use dashes (em dashes, en dashes, or hyphens used as dashes) in documentation files or docstrings. Use colons, parentheses, or restructure the sentence instead. * Math in documentation and docstrings: always use `\begin{equation}...\end{equation}` for any formula or equation. Use `$...$` only for brief inline references to variables (e.g. $F$, $K$). Do not use `$$...$$`, `` `...` ``, or RST syntax (`.. math::`, `:math:`). * Math notation convention: use $\Phi$ for the characteristic function and $\phi$ for the characteristic exponent, where $\Phi = e^{-\phi}$. diff --git a/docs/assets/linkedin-banner.png b/docs/assets/linkedin-banner.png deleted file mode 100644 index 97d245d9f8808843f2fe76d65d5bfe70c292b333..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 44494 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
6^|+|-Phk@#5v77U&;yv@#$K?Zh?)u~a8|HS29 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%0DP4-zSuN?Syj@x4}@!ZW1 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 - - - - - - - - Quantflow - - - - - - - - - - - diff --git a/docs/assets/quantflow-logo.png b/docs/assets/quantflow-logo.png deleted file mode 100644 index 8c16699622a917d04ebb227792cfb99f3c74ed63..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 11919 zcmeHt^;4Tqw0CfK3+~0;-KB*>@!;<6?ot|@;x2{a?i!rp6n7}v;_h(sz4QM1{s(s^ z&tzujnPhj*o;~Ly-@d3QV4#wq0ssJvkBYMD000c@e-APubi_9>-V^$T;-aYQ4gg>d z{P)0&IG0&K2Z=r8Kpq;-RvzA_Zk7OVZ*O*6Cwq5uQx{8iXE*EYGf@%%fC}(YR!Y++ z=XAq6#Xv5IUmyOQQKGV7=Fyv!(e;Y_PlE9jaN!}lvpcTG7mSFa6y(Vk z5H?cd0QqDLn+gD6#sem@C`4LHlAVJl9WQAzX2!EK2+oY?D^eOjNEq(Zv0Iydy0lXU zLb($S{H5Ije*yh-K|Gm4p|i-9wRn_p9a2<{p8ByK16Z<5MUJ;ay z`;*eqv3KEl4r$=4)6HGG8l!eb@}L(cDl1H0d@WVo(b7&<-SRw3`8W0--miEKUyZ{G ziIlswn{guQL$bKJ5}3YUWz462{o^&t=7Es)VS7SIK*f_qaHXW6b_-+Rap41ztE>sr z_j5^?zvoi%Q!O_geoth{`EO#}NcnK+B-rg_YVaRg54jq7Vu&@|kr!>fbjre;+E?AlzSUyk z&~Je5E4uT8=h5Gw&PucLr#dh_+8l_J0Yd=ET-}NkJigq*5)$||V1}2Z${SS)PDxX` ztoK~O<#XFqg;JW_G&0vglkgA8veNwuBLC_RL-L2) z$si37+}Fuy@e91s+s3LkgQ1%j#;C0qL{#h6HA4aoS!re`-K@d&Ok&gu+`&KGo9~Pf z#SCIzIwhsLxS%2i@KLcn)mM?p9(;|cEIEgb=|Uf;pBq}H!~5JWyUib2^^+R{Yw#1G z5%aOu0LpNYB2X~bIn~k>+XtPZHVCb(6*sfzWgFYyxt=k8q(`! z%v@Js2P?jb14$$IFtB^;}P7sXD|xxtIWJT?ZRwB_nq1)3fJBd!@iKycDS|S`8ffH zLjT(XI`A4K+#AdMF&W?D*V(EjhZ?-_hkdU4<`4}-3cXqzZjFwJus!L4-E+x!WoyHx zYIMGsKBBXbw3GTyW}W#(bqFoXE;5pB)!3(RKO%HC%SJNYojNPko0VEvH_46qse`qXrQ1Z5t()PEB4F>a{|3NMy}6QZ;j!S1DnXs|BF4e((w z7|wy%rF`GexyT1_#Y}m{UQyt6LbQ_N3G_S1a2mJ8D9DZd8Kdq9txt|i>|i_mH;%-M z3w}B~Tz3`yf}0Hk%qwU%eP%4EE(w|X=qoEd<-_8)U59ndA7R@=NUN+5>RC~pmj%Iu zIKOc$Q-FfcMInk5y;5QKXK$&pf0y_ge+}-Ga1PPn7I;p478gf z03ySp^LS9jH%KMVbrGQJQe0kbEsMKlhNicIs`mXu%}RzRide39BQuyZZz^?^EMW7u zJu^6-fr7Xpz`a{q4RW^ubFxe>DLg)F--!l9bZM}6P`y7GrqO2oY%;8QY@|7noh#Kt zwS9`!pJv#&%8ABW;z(Rs)VAZ)O%b*iR;Y_dk!)dd`|8@nt4pNafq5ddJ@QrmIPsIt zbjstK6w%xDE#s;_YTI?1+PIOPK`T{Uk{YqT_rfrU!(JJh3gZdelfmkI<1U}*quKX5 z1f*1NGlSV++TN#dCUUF{W46}|&^Wp&hH74e@WBg@t)G9;oroQcC`!xw+rv1eKe}W8 zmtH`3Q%0j)cY?{mJ$4U1BaQx@(uH4+S4kF!8v!!7*M}gUa6K)AuIonZyud<~z}JP| zi9ybgK%~HjLrQ_&8Q1HP40sryhdfi>rRBUwR!$UFA<;NFE`tU$jeck@v^^r)Z_3|c zbzFoKW!0Ih794EaST@oa=^7_^p35s653-IUQutG0CWL?Jx(fMhBKNTRF@;`8bYcGL zcz~Ir%YHf8S61Zy`O=w#fAPgB>lyRu;w0vCG)DIGIW|hU&k=?FTgyV&N0X1C-&nyr z$@skI-V*Ql{QfK7Do{YZ)M2fgSR#Jnsi{$B-2W|LL^Zqf>ofFhrm?GJ`o-Dx)78Oy zpY~j0Z+Mob1}=fsc;zO^4@dW9MSDMh#gGC@jlL>8hK0Nv5DiVe9^~b=o9TuPH+~wV ztCRgn7G($5w+{#D(cd3NIL(fMipIK26?s{&)fe$!{)5k~{d$=5r1Af+=mi@xw@FEyp zEiy^^)@JHDb{Bb~GD24uThwky#J~goTR&s=!`+R--O3^})w^C(uiw3vmrBZ1EA3ta zHL#u*-agr4yGKOfsCtK>4y8)^l;2V}s+pA(P zRrtJ8HFLgD|I)E~+H8Q5O}L1h&B2xc9&qUQ8;V02Z4gpj$bEiUZm#wEnU_%#JQI1( z|5cgk`Dus={`hFGIED+Q>d$siDcrQE8q%G%fjqRgdTgB3T@G-9L}Fx5JgO(vf9WoGo%|$7Z~Qa-gGoV`01Ug>qoq3TsB8g* zJYksbxt+X+pdDC!Au7;bjLdjtAtLiQN!0>dOCU6j-TkzSCFC-%5SjySzUnUDAaubi zTGMsCt0nrjH&~dg;ObfXP+Ntjigbr+sjZLZ2G#!IcG64cw%nZj#*THD#cLcLu#yKC zbaPX`CE_r<&Kr=oO6Js#@5NTtb2@{&Q3ZAvmC;EOyR(zCgjNcxX%h)AEk))}TwNH~HZS{b!LZ!y(H+_d}B8h!Ye_tgkjt&jk2U6G)%w37s?q~23I~`U@ zEP_nzAho7xkw2dWiRU1{HLR1wu5ia`$jb#i0FO0T%*^I*Rk2KKyFK@6(JH`}SsUqo zaXdX;v;*~4Y!fmNAaV6p4A>#|^H`6*`T887xhQKan*WO7;{}P_{V;(-v)gFtPk#M+ zA@X70mWD|gnU!reZlZ@0T35NCy%n|hpHuLdO)TN;`e@Jb%g!PdMw19cQM%uB_~$t? zta7%&1fB+Fw$j-Hdz0oZTQt81L2-6Z+$VhzuI-@-DA1uz9dq-PbOB+be7eoQEcJ$YsfQTL$606c8kW+#BaAJc&3H!(7Z|q=z_3wjWv(LS3ynJ;4N!5GWo--7i zl`*Txwf-5-t{nkr6CVE26^|qa8DVA9;cJ3_(scHlHJzofOGIF6oxA!e#go~u+?x2j z;fs!+%tm8o^fDYK54pxNXBL(kKz3eF)aNrQHW#m!ff2EZ*89IXnw`6#G_kCh`f#A% zzA1Z)20z#qz4sAgPo?Kq(>ms`>Tpto>>7oL0XxSZ3!=5&*_2<8Sz@{)zk4FmPUHhl znfLtp^?g@dXQL9#Z6;+#y`9bUYFJ5a>`ncHcHU&fNgNI#Ov9o3*GD$diw8G|<46)s zC)j^#CB6+R1fR6gi>?&gb3R{j(Uyka*(Z?eigbJ0ob>^7a@% z?q9Jln-c`hR>RZ&4P31C#wOhdtu@J*GPE|HVp_S;JUy*A0~MA@V>=V48eS`!Th&c; zYi4?pWH=IJ;fj& zddnRp3qn{iukB;hYi$pfX&SwuGadk33#bkn7{+cLp!P40VmY3rE_+^z4B-L<+pco#P%IT5Lu z)gpQD(E%i1$Ot(#yWh4eg18YDXGp)@_>bmGQy*}nn=qb9vkVl5mdaaqTegN3!yPN3W7rj; z*%ghSWyLC)i>*QaQCf65qSOzYC|i+$X6tw;MzxFNYzS@aOrGgP6+(wf`haV_`g8{V zF$GL@$_JN6%J;p$Jqv=PVPh1+WgJ9!3xyX_%>U%XR?%j1to+xw(c*1F1(J!PXN9$QP>>La$h@*C{f zCiZJk`_ZJoG!<6PB#X^NB@_z=kPW$us2#1Lib>eHcK5PQ_=se}{KIr($xMdAgD*ge zb3#-*d{7IvEaRy_pUAEn<9FxCqi^xM3YMdVn9vWSMi2L0FbN4b94S%c5|LYBiE|~S zmTU)m_cXCwWRz_HAg_U&1w>5S8hLY2VrUerlT`)w`1S(ca~PAZAuvhv`6h}pT5~Jzv>2P!5BMYbgdCWK_>cpk#XdEmNiw| zGUd0MEo9u3Z!87M2BFgLPCvX}*seBGbJqutWmXYx1oOVkUWq4!A9Q6lh+JF94s;9fnpGXgBl#u^1bzwvaw3LC zfw#(!peD*bBlTBDd*0ama?=5Gie=Yz8T4Ik_z0(0C3wQu3g2`Sg4}^0 zqKg6=Nmgy{s&gxE7>2RaC@#Wtu$4}K&mjVb9~;2}ab@so?=#nl1Gxn0`&R4yMUX#~ z$2_P*B&775^mQ-p`O+qr&RJ?r^s=h>NzXx=my)8#glY1jLt=};GEzSXwdMAX9N?Xw zFptgH7`_T)_w06-S)9b}pCtpnSiE?ASY+YOJ7ii|uKO@&tmCpo?Ka&DQ1>KDEKqL8 zdwbksd_I&L-bI`5hyH7CA>$XcN{2quAR;##)NvX|qOQw(YJ~CZGsx55pTEgi&ulv& zH$MEimsCA-T+g4{Ne&0RC+DDz1?I2t8E`M-u>!*IeX^dpfHfaCdW$n^^QxUmJ(P0l z(|<$9uDDK(UCm}dA6nx&bzI$LS=oce}qYNbmpY zscTBmc<&z>O%+pB=WS%zEndASIKG{yvCYZ~(UC3EHFy2{bjHob6)MT?T|>6dvj0>wN_zilKzaMWj(d`v(oC zv3x7Xz$o-%2HtwYaeo+qyuwOL9h8rBeeIub3$6(sjl^RRI}$pS|G+?#jYA!6zH5Sk zLr^`5pnN_-4ch7Jw?s-a>8}T^W6L6+2?N`gwIs5}>M*K=hZ#QN+1Cebmt{eklo-Jf z!`AqC`@dg|dr6`F^UT~~&x!R^j;Hy#6y@d{@eCJJ!T}=bfhmep@Cs2iV%Qp13NFYN z1<+X^Vk2v*O;}GcE_FW}G3eo3y~4x2i~4;d|MBwRc_;bU1PJ-Xj=<2F!fg-wr7yjr zb0=3BdW4#C)1CysHqgxCD~#jczJWN$#kzREc#HO%KGO3+`awA*cPp_LM5)kE||z;`}W zR`L40XraNfNcxY6SxW0tJ2S3W*X@zJYF;Mgv<#rdaF&0g9|0wv+n(gn7>$mW&Ae(R zm-5&l!;GB*UC_y+7pLN5;56?Ac69iS2M>%$uk_Yy&xP{!Yz3MmZh+u8`P&l~@vrDL zfA$sEWrusV>RZ)O_Cj61$&MN$Z@54}&bvS#~4 zuQTjdKA!2Go?j+pR5B&L90 zjrJuemU{?1Ihev2G*E73PgXkFUvb?Y8e*;p6%Ifj>Ig*L#U+r)>QJ|gneKIG_($B|EHQ#JaSe(Ix8=SU! z9Vl6O)~dY{&H=?BI-0}Z<|yQwA34y-Jc>{r8`@(j8AntadcXQW37DG+Ds}(&R5`VH z3;blov!}1%aUr*`*U802b;+hY{#*B=5M!AUx)!XfVtkMTo%f4alZ8O#A2Ry((^_UH zLl_7o5zQ6P3RQz;Jd<#0lG9L{56E-)wu90ctitwnc5=&9J4XW_>7M#^B>~ENJOH1o zg=%v1tvXcVG*z%eBA4m{i7gLX*j4&GK7jsfYERw;(&Sdh7)!ZcHl5)RJ3j^^eMV-L zo2|Dnb?hqNADSrFjUaYvvH?QgWSYC#gdl=-0IK@^=?W|EzelAKA^ZV3wwZ^B20#l<3L{XUb2(HgqOl*o;U(6%5{9nVI;Pbjd@VIlIN+7j|ZFVJN%-Y{)g^k ze?^Dat5s2NWPBE#xWi4Ex2!x?KWdG1W1{I(S%=f&8TCLbqo~Y@H%imJjV<846Z-yg z&st8++UF$(9F*BERuN=amo>MRYL)?j*ID(cObmy`QxJ~b3!|C6PNCpU=1Mwqc44Jr z&=nDI<3%CFbn+%-v(f25$up$BJMOF}u2$Qz86+qWr#&pvmv^SdiC=r#u0zyd5l+gs z60~p`u$Pbj9}NZ^renIJV4h&v0>E<9SYX+7B_V zvy+6hjv2Pb_Mcm>2}`(7#cA+$rB0N9dLm8E<~xA_J6=D$Ud>nZn>9bhQOY}<+QoLg zOB5XbX_6JDvv0Sd0QabhY<%C|@AC}Ap4#&ZL{hQjR z`(i|Xzx6BVNd;QGMpRSZKM1AbaEa=zF0CCd6r^ze1uekSY3!>S@d0@sK4%IF8x=92 zo=<39Oz9!$cwo*oVDN>n|7wNuH>g))*`@~`k#3W@nM1TJleT{eVqk+F%Gk$CBh?kpbs~`2G^|HU7oB-m+po^D)On?X&!$fkZ3&+;w)A zWD)`OI2E7VeL)?rAAhIR2?wppnCqnPL_<0fNhD%5UpVWYDXF8mf4DI0jcO_uswlo$ zA+uA$r&AW~g%*|;5~q~e%R7=K^O#U2IY@W2^STT2mPB3;VMkMDYZ zdIx*`2z3r%|K|mu1>HME1n%(J`B`JOZj8QF7u3L!3Ls^s>$8y&frz+02%sl+{y_~Y zCw6R#3qUJkmRH>%RBl5bGJMEbB+;&7(i^0`AN=gwcCt)r5~S|KSN~qXbp@px`<17& zJC_~D73v`ot-8&0xayaK#atR*!-^&J0d1+9=td|AY2iP(Y51MEYDK7!A>H1wGe3TF zBfOC0`S3=CY~=_{I0s`(i>n&{VkrzJ|GM&;xixQ|L-z|RfPH0Z8fF5{UrhX?o?En~ z5dAl_v)fdBwD845DAp8ky!kET>4zAlp1ZZ$eI5R-DS>gY1NN<{dp~n(+QlN0sm53h zKRyVPH#zZQsx+~DDUl8iYfCKFQYjfqgnK)(Aq2cuh9h&WpFK!N!BlNw%kwK452?@e zCd-_P91Zl*9(duv!?XqZ!m>D%h7MlTP1|unRbEvI{=tB_?MSZ^l7GQf=?ws^POP zJG!asQ*8O!0dl{uoTdHBwvip;sr>p$uR{Hsru-m_^I~>`mKR?!#I3EcEp}-uj#F3A zj}N9dD&OA+*;toL&)t6jDxD1!;rHC`g)k}oVEJS+W2PcC#QRA!|6VH?lB z1M{%At@lbfc(SQQFAMzeID*86VmAO3ff<=7XIYq-RdOErH<3;}cFQnV-W@wwz;Tv@|zn>Sd#WIs_wi=NhruDA0vm24e)au=KeJ zbtfM>kL~{B3a6Kfeg5oFD?2oL#n|d{yPUr85>6}adL)DyKEDY1jqM%@7{cVo3-Rzk z@7eIus3JB`LBIZRPr`1&axZ)k88ab5*M%Nj&yxxI_qA$DAW=j;oD7tiO`47o4CoJ+ z8R-(-C>AvP4uR_Iw&X$+S!puJW(k z`{Be-ml;}NO;ixk4lJNbb%!5;$8E=~yS$Wf@AwTz1tToRt=xZ7Wp{H({GDjn2exA3 z+HRykpWSX`kF11obOgc?O)ZGhak0-f%Rq*}+FRrVlwbe1M^>srf%fGy9%phQHf0(P zX&RR(4J|*7xrL^D4OPJx?Aj;GG)uS!2deEk9Lx&juY3{VP`#BPDKYA)?%$}8dHxBy z$*uzRKSXXQIu|lTT7)X$7iF>8&WfNrzaIQ#3n~&doVc=#pv>vAEI>0ORW?zfZ3rC< zdpf2rtSD;mXFRCvafd{G@)jGPE&zw1O~8r1Jy7il1po56I5Smf5oA|LLmy3sN%-39 z(g6}?F+0t^72J^dEsFKr&2K1 z8OoB>4c{L(INq=-NlewqpS$c2hk@i_xDmo_SW()f_B-sQwy>C#*EFeVPz;CljpC`a zBEg1{5FtnCu%(mPGIKGB!?w?xn{7p$|F8{$YY-IS{7wp=9!RQgxb_fi77HLezN~Vl=K51rbBN7f%-LOpJm*B15gh=qWl)HUK%(HNQzp?q_ z3##u)F5A&qP=bEv_Mc6xx=Uu?`5e@Cg4h9bljnK1&YA~1eit7ayg5Cv;Z^)dgex22 z{A`cxw3=|#6-rG6z0?w*HFyvjRlNdxSZJC*U%~f0QITKug;le$_8ER19ix;?tQI;@ zba{kfOOW2uR;n3^vC!+^*)=*5*$Xd4DNC?%>9ldlD|w0rKe{&n$&$%i{aKppKJ8^+ z!^;k>!^!k|Og{D^OO?|0anL8F)VV5Q2j7RIJpAooj3@i4O{4_X)oaDbNY_O2rb1a` zs@2Z3Z`<~l@Kdo<;yaT>?ke_|4kBydMpXPc zHI~G9y(K0vo%&VJ|m2%CX61)=A3D{ROt8pb=r@4RP%(vNT`X`@3BAjos5$Uxc&y?u#De7 z_1e@ZQ|^Gqsxyw^Wk_MD0yLgEHnP9X@7&Ft2 znZI{`!7ez4y+VMA;##C%2u=24U|WJpk#DyQpM5O$>)8DF;LHu@p+1Oy1`)XBn~#Y` zUItNtv_bs6<#-0XPA2JQYLfLwRV!OiG=I3ryIp#W2Xz7XcSMH)SUcGx<3IX#J!y-j zE0kwWwx~1~uDS31CYoPe_lq*ftAV3*!uZq9hp~HR)G+^BbFej!404O6(X!B2eu7rD zUT2t&2snDg(XUm_IfmA&;Mb3MDqbrBd3585XC0pS2^*AOTTxpQtcF@3>Ix_NbJk_L zHci#s?P1VJ#nkfscki~G(Fxn@5pMapL0anhe%7-{Q=>5dV6D2-Z=Tj z_Rd6Hpr1SCS~6|Vi?a<|b=qjpdLX#Y!b7|k1CgcYLbfIP05@qOHS7?2G>wO+T^YVW zNOWBI8M7OMQS0v5D7m5afG5iIZ(SUYuGNq@{je4<9Q|yxhXXt~kSK?vF};Ju@%-vd zk2TwQ)_#09BHN1NU%ro?(Auy|?%C2S=h2C=?mvR8y+K(Ez9t(PScItWDzG_P66@i7 za}2gzxmEQ1_mBLTChw@hO8>`rCbWw%_A`UD+$MU}1z!F>N|T7pYqSDO`MqNm(wBM4 zF{e*~eJ&TuP7Mc5z6{J&BDy|b$$my3U84Z`bx_ih24O@wok^Ox9`Vq%zBZRHQ8f=S z8Oo}`r?Gwfler)h9Z}&gxp@bH4S|YCbgeJnZ1?TU8-YQ`*^+S-Ri7sIQ`pVcB4B$S z_W%czQ_Ff-JS)M-Lx*5E|AL=L1B4{WU5p{+XGg zFq#TPtP4~HOjm!S$!zd;z0dip8*u##rm0nXDWuC>4|Hhzjbab87k!o}ltmbgvADTp zIKgZ$d`s%z+g^pqraNS^q9GAS`^Kyw|m&j*;4 z5$~yV$E;s^0?-xvyrOm1Fo$Q<1Ut!pod$=`V!dOpj=C!S`!rf2SQ5jC4B5Mb6=pba z?HCC+cpE3!VXBL8k;%T^ibSO`m=$v2V+$es8&LpH{fWXR692}6az4qN@y5}7F_kW& zw(9r8}jbn$MV ze-xMFr>V0FlXq&$%~ha$p&&oi`SsD4luFeP8hm|s^+Kqu(yTPdkdwcW*ncjD2Yt1BmI9Kd=>}H*MBtiiK zy#&ciz1Q+iJ6Hy%eVX>$zCSKc6H+crKI%_?g^T-v^gG=n$tMK#?J+u4_j3v5wFiDP zw$z&!3sEyB`u2wQu$j`{1YH@l=UC5Q1_kx`eDBK3AP?Dnn*Kpsx5*6oB2Sv1YkJyq zPiOh2#gy~G>_~K5V481Q8-A1SUN(~PUKLm->K{7uUohJLUV?^Rfgb(uCHha$^Z&iV z;zF1B->aAHSfKws83=mwe-HlO@t{uN|BT}QT;cyB#ecEj|6Jk!4_9DY2eQvfGD#TI z1USXKm63I#R%UHv8oQo7o@9`TSh+tekFM}#y$EAPTzsr38^lg-WJ)Z)*Hm-&#Qp4` z1s)L5RGDMjosgDogJ1}5)?r>~l*!hDmFcCH*(m6|f=?K_xk4S1{((QsOi_C>#nLlf=Z=^v_-b$V-}!MQH^+ejZD<)FFNj;}rESC}@xMxnFt;`JeGoL)dV;ozul z-Z8I!_8x5VM4_66`m;gsJzUppho-T6mqI7(T7l7+eV4PiqM|HA#c(;?;lg7+tarI- zR)Z;sSBzl1Pf9CygMeCyVlq0q$YHSr!j4*w8XmetJ2+u|kW*{#Po}nScQ+1pyp=p{!MAmq@%|XT3bej<(ZVMIE((huQ$0)71?=T3T^- z;uumyLXDfg{I_sLg9%d&h@pkJtg$Wyd6eCin$j)&r#-Tx;q0;3G)nbY5>PR~^j^{H z7(<61I>#X8gk>^OcwYtr=X*HpLH3hWS#`8qY zzNOjo7Z-80X3Fm=XSQk^>VI@@vnUM*UECbynZV=n>=twmNzyr z`o$?V2$>n17^;lex|-UHSy>PfwBCJI;A~CN;TYvML+#^27KAk=pXVOYBz7fEyermm ztnq-y2+`BTe<)E1%{*<6%lwX)Q3}PstCcJkgDGAM4CHd!?|m8V%kb$s)}V;7lrK#n ztMzo(vDYCcd3J6u6XVc3ahWbJdM_y>+pG5)7f_Pr59~xp4%()|igj9wrZd>y z>sH$i{-q(~vsiAn0HJ>(I!gTG=OFZue3hFZp%G+k$g}Dd4#a>i@A(|9Vg`OFx1O1& z(FvnM`qk;psPW^`TE6p>V;iU5*?W#|-SMJA9{z2QncZpy#?)J`sLzyQ#FO}$4zmve z8~+pjvc2<%)-7;#kDhBKPX;I-Zr?vt@`?bo6u3`fH1tP(7LEfDu{)3PR;raiZ0iR%?yswVeCRv4Df&EODomN68tP8FPW zV!;gAXu5@@r=&$*8Kb(PKn9eF{vuH>MchD$j|}#~%zPW9g?yL8gPTJ%W!H1jk=lEW zYbN@YbtzGYWRN@0h!wB+zr=SO`Bpj{ta}5Bg;UdJx5f&C%!%xx|GYyp0+`vO;4`Sh zDEUM9F)Kuf^X99$B77T6&Sxo27R9VDe5v<`i;Bb%NBQJfW zZ&qu1wH-5^##zaj$yJ!y>?3vGY6(;9SgffRyt%rt5b|>$IR^Sm5QsN<>&^q4H|cMI zA@QyOuz#6gLgRt72UbAN;Q<_Xsx9D{Zl+%UN3HI)aZgK-Rjup&f)EJl6evheAFV1)05QDg9FNiUZ5lPSoc zMOEiGh0aXU!4G4K`yNcXic`dBc(1WBq&sh>%;Bg@(MWfI>;p@DWWI&vV$6oz+E``m zPkLqw&-kAZ?9kNPS@_sP(9zY=YZAqdLlIPWtVT%y!vUojyWL-~6FkVrkjOK)UQed@ z-N1B2Wvm9R4PM{H=Jn-VD3moR1-Bw@jRzomHeip*X^XvGr#nr5>fVVzT2gN|2qGe6 z`9vva{we8I&;NG2{uS0eu(+P1uKJ^)^wLZAkXiQ7F|w)I!IQIUdeT@&XnwBaFeU!6 z-`$P+^35U5=2;B}Dja!(JwWI0w){@<-8qxM(@nDC-^Y;i zHi62mE_RX!c@5taqhKBkx2jM;4_t3TccvFgZr`9%-}OfQa4B{QINHdcGMm?Njh60a zhZNZMvuctPm607J-=xcp^~XYLAJbxkFaq|G2KTge<*i(J^di- zPlm=@`mY#PG#A5j$C3LWNk9^El#Fl$;%3|H!$CaasdhF+Cx4~4k z2u~5NN`FKh^)$yKv;VdvyvIPD03I9K6Vfce`iOV+Ho@ec+w(ru_o1){~UAso6DQ(i$j)^)?EXHks_)K)tuSeCJHD|c24)lA^G9` zUlJAA=51&=3m{@pQj-2R?R>#&db%;5} zb`9#i=(gc1bH_7LfFJYUL7LazyuCkOgm~80B~_Y@!Ec|(6k1t4AKCL_dophq0dNABA=uSEaZ zgqkd5*e!@Ykeb^BNCqHBUDLrbI@=jftB&{qdS0Ya zQ`(JDK9ohQBB!!;HOl}Y39I+QTAMxZuF5OrOr5Iwazm?9X`!lt5S=PE3O|p61z6~rkUu#YP7Q8Gm3lbP4pdlti8_fe zk~d4g{HcOyOqmSy)n0h$)cB94DlLrj(Wa;sMOK^%hZ5cl%--^fbsQ1)R=YE0S1c{) z)?-LEkd)jO>3rY9T*s^j3eCC?M0j zt{iIY_?}CQd|ccwSGP;n+%x(3PlUUW>xPl>7V7xM^nfam#hd2VRzAjB*ZX&nF6;w7 zg+YGQEP8q?eJP1zxM%XdykES7TxAY_sAosY* z{yVexAS|s8R?B;i>{s5K12mWwX~3bmyRiDUkmgi0mmxBREqrO@-HdlfZb^3=$@B?f z&+8m_>zc`I5n|`BKE6KMD;Z?494~qbNUI@6m&n3?WYFuK4@jcnl+SoG%JCxoHPz+6 zXjTT2r>V}}?o^84m3p~~Lj{V=Qj)pI{KcbURjdX#ef3mrlaDb#KucN-Y20kTaU}XCfW<* zTY{E?^JdkL`QA;ACgL0O=G#o&O~7eI=SMOELP)}2`JD?dr?4j7llYxIbvNMG%l!6V z^>`Hy*i?*Y-Q+Q$uchiy68yrVg0dt}FpklSoDy=s_jLx!-3-g3YpoH@m(6tI5yQ_b zPX2w=0FE~5D)rzL4M@Rw4=g8;R06oYVxTL8DV}JbuEw4>wR!B=qJqH036V?>UT~h` zinTxUcE^Xe%Lui?Q=gN7!vG#At;md-M`TAgy`#aXe*tP=V?Z^l%@Wn}a@1)#mN&dB zin3KqF72-9;K#B|kJw>eS`%6FvZ*US<%}c3W6;Znq_n=U-jcTle$d}emM&nN7@La< zNmrq$eQn2SQ#cKCNI=}`mk!phmwDPg92r@LhCEW@%k`;B2=Nnx@{_#@K&6Ia9Upv@%>gPQ(e zJ_Mh*=4dRB>L5$H+s~i(7EvP8(0k{eh>K;n2O2yAfeKBgGB(vs@Nx-?FU@ncR$#CG*Qh#FmRvlxSBrZN$fI zHA&%1x`+t)3a~1MCKR3?m<5;>X?ykgz;WZ^G51~x?_FM6GKTiDAq_-(vr^aINZn%a zxIsC?@K*FjMO?5@t8LVcS<#!-TJgzE4u!?(Bz%8ew0R)8vU!*GQ?b!#!Kn6vL zx^x6P>|Up_@eLm>A}_+na$-wz`^_75QKVbX+*Q#E&*Fs4w|U@v$tfuTd4U0dJc>Rs z1pS*q5z66%Nz<{fs?`@%!(z9(e8q*)K3*pCj#f?7^-lb=_dufb6F-Qvck+Bo+V09G zdgt9-d76k%It@4E=NAK{fdYU?$oEn8U}A~2)^u-P4jXc;d)nSrOKy)yXQAsVmi8er6y)I)lmYuz|L;nGL5SU_%VbUp z{iAs-5#fsDUUAdOx7IYb-`c&D7bb7x7B9hoEuU+-F9+0F?5;5mc_wD_i>Q7+uyu!^ zIT?r-$^}iDqPF@HCF&2WHQz-SlF6sTP+0K%Dzh)yue!iufvB1H_P}(;V@PJTv95sT z#?!~Cc*}w@7Rq174%`kc#LCbBC?qRS)rEm9Xy>pr1eA|Sg+w#1FHlv-b2=cn;Q<#> zmX_@Yzl))5l69}Rua2&C2kyOFAmGy{2iT{~hpz*&83Npw1)e^^T~cJJx=uWAnfBt{I2os+TPiSGiv*P7DN_&@xB$)!gbrNx*5!+j<` z{!9lD3H=X>0rb0Z5nGbUKv~9Wx~eP5<8yrxcjm(*UJYaoyTK%3TVTiqlJGmV#V>jb zboj3D(PELy6rfZ4o+?~&3K4r%!E5i8(b>Sz<{q1Nmo)C9#7ga_4uBjG_N%zR;L4)O znf90kPSymv#kzk7{O-%2xVq}tfkf;0$zd>tA8JOww;kh4jB|@}SH5PH7CekdJNWBo-%;$5=_;V&;J*0(gaA=ORH9=!Ujgfrl z^J#6I$cJrD2P11Im^>gBbkWTy*8W@otYrZaJ^ng(S}#{L-7 z#v3LT?YH1qsveA8ft_LulX!(jdupwkDwU4uF{>F0UQ>us@o-;OeaV^VU!}G~HJ~-G z0gUP;Aa(=ZX0rJPsJ9iQ0dJ>3UV5@bweAhx<>zwR-7U@z_S2kMK3oIWkXdm8w;2#7xYw~r?5Xq%*1zihw_;7uCc7!kfgzYCXGO~?O;irf1}Ny#t#?pZp6Z<}%x z(PaC39mw~&4vDrpb$b1+aTpztlx!pX_T4N^?}U?uTI=jG za_6ldQhVAw^8wpNG*ifH`0vm}EPt-VzHQU37kopYs)#w1_HcUx&8r-FJ2e}*Z1r_X zt5Z9`+3%|pup7`85HdWswj%BJvPW&#GongG+LjY3(&jNzZXPOZ??xy;MIHak4^aS6 zoXNTRis^q{Fm^`BTq1>nY(4PneZGr!&cXhu8P6l23zP1&>YUdF7ySGgezRCBV0OT} zI?by01ckEk3VZou`f7-r{0_tP&$}8>j2FDG4!g*-@>Q{Ri?TAkG6c5DJX#wus>_p6 z+IVQH>EBx)x8(he+fXdm<<@OuGU1tM{(op_YSfF&{pB(v9bWDu2mZ2ep+jjj;WvW- z0L@LxH&I?cq=v}?Xbijo0*>z{aOv+!5aLCs78?pvDUO(BjoT|-#?99!x%5-LHm)zd z+On`~$ZtDeZKNM|M5b(+z_cs74da(w%47DS2_(Z)4$lO@QrE3;?S~8J5|K-T;hyrD zl1(f0cH<9QLOrWd*#he_=$%uB1 zbG77;kuYb(fPQ>$U8%>(TawUBwd)-mPvNpovbCUf#X6R{e@5MyBieb}kMyGl66>0R zpTta0y11zA(A-JS3W9Mc54V8U@-{>KIQ1-E3ITQ%o_R8YT&9NhW`ZwJsZYU*&i zEZF5}D!rd&>%nNUG$0IQ7pNJCmi0av8-$p=C(|o<=CynH?1Udxn@HdQRb}9l+CN&L zD+aWWYIwA7i9nYKz}|sh4g+I-8x5VlA+X(C0-g2o+xO?yIplx^Xw*PrUmM#K9~tG!S^YrGWy%g2XB)e1 zeKrLf=gr~^FZ+@g3ISjf=+RMy`l<8D(Pv!tMiCEQhNx;dhP^rW>)Ck8Cv7YH`<3y- z!S>>)zz^C0iijtK3JBKPBZ_WalboG(b`sCu`jz~^SNFud27D{?E?~4)o5oK%A46Qr ze>NS6fXQsFPN;FqoC`2+;n2!ECf3j1fc*?!r`Blsur@>}P3C;xk3=lR49M0MU-jVg z*6%+9${Gg6OfpRfl$yInia4Ufi%nTYc52yj*7pGV%#d)f_dk=90%2VZqcCRfe3d)> z?!-3LD!WNDi{RIQzZd8sZ3og$DOqTJRNNO~(7PkyzkO9W>8@8Cy&l;BxC77yz8vnd832aBZcfA}?y+6=)g-BU^;Ed7a6+4#H%T9_( zb<)_XG1X{rEZ*%WHuY*-9~{xOa;vWbs)yiZ@PPaMQ&A;PP~=Y{(39mkZz%)ATi0fx zIgJ0zSqA_WuU;-d!kQ{tHPaLQi#gWdi@}Rerd=Plr@@o>#HOzD#@iWDR}<$`x8s;o zt{nmVv=8^J(NNF5mcQWuINTh@A(jhuM<)IFz1chXfxsa*L~?~g=)aP<04T7hq5*h$ zqf=aW^a9K}6Hro78?=~cKOT=Pf({}JJNr#c?R}cnatw_Vk*%c07oNe*xHWHwKjhs$ zx-fz?3vt|hEwd@`KbH~7*Q~_{^}>Z-qIX#B(XC$c|4)Y%N{4)&efno;t75Toy`0X* z-K1h!o6$1uZN~Z_{20s}hL@JV617tCXAl3{cwkXaA>AeRv(p_kN0f2KvS-9gR>!eU z@Q!(d$OBpXHCdlWd|PTsn{J3;0=Nwc9=kMRbgbWhZ|tWa8(@;%l~o`YGo>Aj=ddE> zciCac_+Ytx7z{*Eo4$V+@rO}zKKyuzX^L~v+quWRG zRe4$|q$rR$iyY{%Lh@A~YJ@niS((#Ln&S{w!PEYi&ZQf7;>GTvIr+fYK-O{lp)e&q z&>@T@vh;i%rnN{8b3#=SJc{hq^F98)>caDaJmUNO7>bjq@SOx;`Y)!uE}cv6@5G&o z=wZFFLf7!({Rz%##-G)ado5R-@q&juTiYe%ipf0w8+spY<$BcmxD`Qj+-`zA6@taY z)Peuod4?9c4R>x8xG*OYv;^$%>drYD6cYb?l3*#Z3%VHW6B^e^SA#r!CufcX*-H1_j~ z7i&t5X$3lh@2{`(ZVwoDOuDX_GA-4$SZx3q0%g+Jk`gTPI!rmx!3UXaDc#{7B?f!i zs=r&EZfPGyw%)asWpA#y{y*~uLdBFCa3G4xT~#vA!|F@-F#?QJzbTdd5)wa|<-;4K zc>j(k>k@&~AMOe7wxb1+Vh073=V|eupGQ)9JE1~3R}`?h=&LH6I6X)$-0}s1af|dW z#erwy!j(EO4%hz{Mxp9991l#R@)#`WaXs|ocOUGT>#{S!-yP{t@u~o|h(MA^;I>C^ zjYHIvs{;(zKB-P4LJ8CDgtzPM^wc+O#gS3@F23(Af+RKQG;Tp-bx%QtKP*zo1*puQ zqJl8$p1x4XrC&Xj7Mi^Rq-1-CP8f4GzWysxPTdF)veeL0@ywi;t z2uTRad7Hck!aawg%+5xkB_5Ns4_i8J5-NKK%BxMn29@8`7PZ25tcEVne;2Y{gfl{vwZ15|`gC^;glfKc>Cq)Vq5+YBWy0?(&=YGjjTc`HgtNAZ zwXK^6$F@FUwG#n?UD#!Y#&qi|A&@#ofe=WP$589P%LDSTUf|yl`+JTKvi^%%ZC^)o zzi=@bZ7~6*Rwg23EorZs+IEvjETAaR3b-gX3G?Yq6lQT17M|yF*D$NURz%3kQSw1L zqHtkbrf;m&EvSpqAgnmEesB`CJR1d|j*jni{Dxi62_Rplz@eCj*Ha;yY~ZB&(OT3j zb|TYa;!2yW(OCV;tZy&Qw|G%tQkEbJy8+_fHuz~<7=DKPlD+x2?V0SD9unF#r28Mf z8jo1e?^-Fm`xfOxc9f!aHUOqmsC*a(R#$2RKNSWUKD;&XU1&LeTiZ*a7-*ij@0SaWwvmbV?cv^pBG1d5a1(CD|;+-Z4>G@Q$QLVKO`2Z@< z&0SVE1?#6%*DXvy&EFyzAr}b>31RuatgO0HQl9Sj$^GO6nl-!#z!fy|&acq)egV!{ z^;+J?>wy}%ge^-lf;-b#(nAPc7c?)y;2J9RL*1Z0+xZ%)giEmGM2Y2N$Aw?Bdz;d= zmT6(f7b3fTHd>1&%KO2IlfA8Cr02xg+Ls20?-B-D9?(Ig-=l&g_&QyKC;a?%*Em`8 zTyD7m^1#YzR9A9-m1OxnA(6^uUs%CrygLcpVh_(hj=r6}TMr}$#t8(4b&EI(3KmwY z434n=g9s1CB>amf5u?{t2YC<5_VB(_E3rAy1?PEe-y3UBKL)i&)m|35XDMXc$Pm&7 zmFsPZK9rS5#`AKpCM4^E^tgzB)5V6&kmkOU&H*ZN$uIQnps$w8dtadqHVTK1(~koH z3&lYJs5%E%@PoRq7Vme2H{J>{5D)iFkB3!&sTAuhrdz(Trn?biCoft&kD!m`KL0i{ zOfF>n2(-tR?BRJ~8Eep70wgUEXzDTAOSQ+WF=x#|AtxrUXrsp8PCv@-j>(s+szb}N zq{czBu732c{AD`-WPeO*F2-|-^ZkA1eGA>F$qP)74RcE@X31K@Jv8f;_a)@OxXXfW z_g&O@GZX1>3vaz{V+BEqYU-C~5~HzOXDyDPv84nK=3S!MD1rwxkioO#zh77y&gUlC z`&!&Cjgdclcap9TkO&L+kfySd;uhEiJEc|k(9~qGDbTB8`JQIE>L2MR)<{b+w;`05l5i@Jbk#*mrCLsHGv%T+)()Q z6bS;AqoDe)x&s5%+jksY;E|=B=7;1|2twSRBtsM6Lj-`527xH{_k(IF*Z83z-vA;qye^T$Pef6Oz?#}{Z`zmcDud=v;unG`g%t~IxJWcj>NJtI1K_Hpmk6xf~=dS;7=NA7Zdxec&7(?H{#Y=Ku^LBwTF|3^h_*UQj&wio=Jd|cfM9zZ7-AD-?7@>PYOWbe0LB=C@X5tDT-fr zG=K?`umEUeC0Zi?;^6dGB_1dJ8>a3%yFywM4GLYVTAuK~HOVTaE_0eu*)CWSxz^Fi zDx*K-fxOC_DAhU5oVrzSeSXea=!wJ^+N??;13l;Z?=Yer+5ILQE5Evw`kuU%FQ0ea zn)d;SSfzU_^A37|D>UR-+uWAdHH_ z=1a8IKU#nEnDDZ$0p<)pba+2ykg?X^bK}UT-qx>e-Ck6+DRD#`BoTP(DfS!W-h8Ct zyNL-*YLB)qm-J6-gN?z=pGO$JP4gDq9SzXtg1LnVv=KQAn1c5npeF|J4vI%5`h>Y@ z%CD0^DT*RnwugHy{7`nA<$ z(yZUd{*B$_!Rv?qi5jvQ*v&^JS9^^BMgR~F;>uY-CPw1zuK<5K1%zyQ;Kb5v*#hRc|kD(Q>q#qmY;Z0dUD4Uu4gBrt%+ zl(dt%%Gcv?}G(VcE^0HvQ8Jr=z0(0Ftn9Je_I1v*zO%-4S-1pW|sELM5Z^ zZvcI~o6UnweCdf^z675w%?RrA)gKO?w=o)aiz*Mg0}w6(hi0oN8>AMa!^TcQN%@d6 z>Q;aK&Ns-?RigBJw~?{yX`Bwb^U8^8%*`ze&_gi3VTqsHCI&rsP`*_}6Lj zm|1RnH-oYoJ?gX{HV?+to6^ug9lgSzvz}OGB9G6~R*%aQ{I*~^e#Zwq0s37E6tUY2 z17e8$g`b=9p}3yL+#hoJ_qMGG}bq#ql2u& zGg&!38zT`+w@U#PyGg+O498>!%JKp@SH0>^B~SzM<5FJ(=%WH1H*7L&9*GZ3V^GE8 z=|M|Dz*TC@HUNbV4~yLNy1C1eibMif>#i&^>j??pi_z(+4>0v}7k3~st=x%qX*t~6 zp|`)RWV5{(SU@VBU;mQ9rIEt`F$8s;-)`!&5rNP_Us2_8Ho)eH^K0XWwDW}lG)Lb0 zjeR~!PS`pBCfL8)YJ>0V0Zu^fda8KIbwjYZT&V1j2ihefVS0I5s8APkSt3Aw_tPQF zcTSv2fK(DAkokOhdj=?gfr~=1pXLs#O*H@m2Hce4;50quX3crpcWIaQK4V~G5$H&0 zQO*11JSQ+#fTOt&atf4>Qc_Z0)Vh`@XKwm`8x;rYAvN3ta|z9nX>3f_?eM=x(5W#Mb@6yU^X&0S42C= zO}6#yQ1t~lY6>giha!`CZrkG3yc9J3j`zc-ib=q*B*M#u7-pYO&Z87tO8dNcQ+1@P*^rch2 z6$9Lo;&Yb~*-S#L9enM_jnMTYp7gZlkevtAEcEMFAW#F(P5&_#0Enr!0E+(|K&mb3 zO|@t5uMd(1c>Q~8m8%&)?(XnMzpY=f;DE4^`v0+3496>Ka2pWH>^8V1H2A*m&3r026f{Vm~5cEu>KJR~k z_+8G@`cL@g9q}l;?ajFO*x!5DM_=(~L|Jay^xtop)BoNen+aoe+*0@*|&06u6E7QftKpnt+|3k!`dIbO=;Fx75 zz;4;zg#lr6nG93&-&tuIHGXQn707UOpGRm9Ra;C(sslZaXGONiS(R1h4G#&vm=2;5 z-XAIYlmz<~J)za*zVPwSGLuF5SzR8%?SEy_u2DZ___%5KxcToa^)-Yxi`WkVs4-5Z z5j#|*8-CejzL)^a%Zd#CoINj10?pQ&=s z4R}Ud8luWCX1#kdIUt46PfY9wOM<)MZro%B~P# zJn*sN$n^O82# zj-mcEAb83MmBmZG&Qy%pyE^L|r`Ji6K=YGXgFIZ`6$m`*xwui&;Nf}n6|2BzY7z)k z-xL)njEpAMSE?4cRl1QnD;&aP0Hm7~g5T=_cs3?}w-yT#Ho8PD>Z4ybqJdAI9~qQR zEo7>jcX@`@R20oOIJp`GXG7xPKA`}`So;l|C{zbP5b0-43#WQ0i4`tp9E|>d#sRg! z)ZcHv77%U$K%N&$UyHz-aEHtclIv|tc z)Be7%U+H@*|3$%*;I}cV%kN4$z6{j4dISClUV&>X+j>UJH5kB}vLfuy4O(;fkt!=c z4)rJ&62~r=M6x zkoF8GL*0PiRUa-zMki*Ec62KHoUGb?uaQu^z`Xi|O|e^P)I>atZ6OPQQHd!IZ(8eL zn|uV*1vBi^02D>*=3IKect5?-VLp>>E$8}j=(FY=dwks4%Zqo!LZoVrg7k%atk~L~ z^Fz7-32jKTTFAm(r#U3%reoufBJ^7_nTlr!n2# zYMJh1pu_0YH@nGI3Gf&~YJD8_Qgtgo?FQ>ke6})_sn$P-kwr$zY+q3QYiT(~`v~xZ zr-la73H!TE1hg_r%T+7Eb6xjskvHPEIZB@mPRu{cDg;_!s= zk)$PuKfH$RLndD)q#x<@Sc`$;!sDi25Vh4q#|Phj3;hXTqvgihW3i*w|N1l!zwEpm z$)h&**^Qei=O(Iw8Jnu=3z+g0I93!~+{+5-t$Z)|?eIGfXEb>{EWh`djfbA*++$={ zAH{ss{otK4~4i`Xsdx8y(iQPVYybPY4}PiL{=sGVfl?q$@X3KVb(M)#jXS zPh|K#{T2`E0P1~Sw2CxspTCyzvL=_!aUq+eg_|@!?=4#ayg)x#olY}VYsdb*GIss^*of%5;I51n z@K%`)JL{eyg3WFZgOlH}Z$B)&Adc5#bwU^@`Ud+20mAL>KG<_MKlN#m3?wyI5iU?p zG_xJyN5E$aWCC`^ZI8~T7XK^n=DOAt{<<=MfHJ%7Q0~x-HW;G=WwN^+$xAk8`R$Zp z7+j`rGWAB4oMlTCD0X#lbsko%W=(+HZcyV5kh?3X6**fRynY-dXu9#4o`nPh9~vu?d)K&spg5CA!HeIzOhdf2DIJwBnBad=(NjO8Dc*)X4bL}gVitMit zUI63U@5Un6U}`=siuSAHAhV#~R;+BT?T3w^0Ov%dhMO^Z&8F*=w-yyq&6mTRLx$Cz zzGSD(z>d2_>T&d|8uEhhD*_ZT6~d%gfay@R88!9hphA|xqd?Hurwl*l+zFA(%9IK< zxu!D=P0#sJ%ya7z#g8{WJrtC)rpkyr2$WI_3}8Q(+f?8|5ZdJ3nux<(rDM}{ItdrkPNJ0HkYwW%hqY^Tq1{ExN>-k5%RMjOeT zS#h^<4q#{S&WSG%6D_8)lCNyz@dul9Ia6g3@V21SZ?SHBzkjlIzbd<@{~=Lmv0d$9h`*@bGTaR@*1T%0}1@0`e2Cv%{JRp5XMf7}ugf z`{D4($EC$@zfnR{Dj_d?j9YC#%Xxz&CBM*xTykPD6Uc9s}Pe6NgVHVzDJ{A02 zdiA_sc|8|*Pe>V2d=CfAJ->`ijyvl*hm)#BeJfJE*f0C#Yt`M%y1ogmqU^sNq%F@ z9tNrxFFec~BzwH4z9n!e*TIelUjDXk^{$#JEx{MD;TZ;y!n8 zy5-%siWLDgFhKy4k+~$0sOuRnp72}2^hG3H>}&2Ykn&?XL4mIMeQg4$I>A$B8>gX< z>K1i7`oClHHXei-PIq`}cf<`+R*MkdDN9&h&=?xpQyd@Hc}@2uck(H8Y~%5DEcrXU zHpocIa{O^>IdLy*tQLpOCLv!F$OWP+d7i_H1@2uw@$g3*k){N7_^!TwhvC9o7MyFw z-cky~2K7bKN}Qd<%6W<7vA zVjF-2~4v zljuJr`xZ8AtF0JrgR#zyUKHX!Ep0{j6**7k@|DswvA9U?K2@V@)n0|WNed(GZ5RTc zybmls5sD?q8m_+gjU&9fi+@e1ak2>s$3YTHOXyZm-ahkr>oR0x!&6`RjctF&MtLJ< z`YD^U;(HD*+&DUF(*_GdasRxwtozmE334>qNWpO@mw7vTcZ#aAM7{#qpUku@!R|0?X9QsqHu2!F~wSI*rl zn>N=t8`>pGlNatlnpcAU%y+#zn}d_zl&0%KcO)qzdU7I7W+>!iC+Zzr|@o(_L^(a~j{=2*0jPmlL(IR7C z8a&fRXY>_x;SQ@Rbg!e+jeBE%x}l(v?JOqrXNV@(hS`Wf({61_E7x86A78&pL>YEr zAe7ckX-hffiE5$#QEMQz1kV~?>oIViZ)SyLA~IvDjV%J79m?mYVHjRnxhFKXJPP_% zq=yUo;qW?CXcc~EeNqEgA9E0&eDw6F&T!4CnPj&E{Cx2g$%R#h-i)~YZDveWYi4i% z&j@Bo(Pa@?mC+Gd?ow3&GAfoKHikMthYJ9`%&Z#l$6RO0*_iwe+=5C3ia z`Hq3V#Dlgi(lOuY&?cgzo>_}$Z();OIJsF#q#|;z(Lh%n>_I)}-X8v@H|=U~oALS6 zWVo)Wt4~=G=vN=sdr+Ip_NVum>Y#T^8y(>lvoACHcr@!k)o-72wvu;-Lhc)Gx0n)$ z)iN8}_`_47$vxqQAEcuSn@1xSp#l$gmkC<)BbmTr6;s1Xh3A^+@Z={HxvRlq(Z9?a zs_##dFe<%w#SNv%C`dhDvk3G@wD*X=U)DAGQn&#<3ktAyVQ+m>ixB@d7J;PBX|6k1 zESyl+MyqJkwz&3^B4|KH_J2*Rigsm8WF`4bU=@^u<$XQ8&iS>^|Jw(ZyT7NOMILXpP6DNQD89fOyfgU_=a9x z%~b)_BoCoX5A}8CRq>_erv0O;7ItlqNv^^Vy)oT0$Li+{u>9Gn?qq z>WX1bfl3(8=_Mwb((sAOjbwsSnDw@vG)Y{Pp~8H6D7YWx?R0iZrkzi z3f4fT&w$W7%$Fs4OLkg}&X7)N?XFM9BOk^)wM`SdJq?Gz>5+_dcXvO84#c(ERL+_* z>`g9~O3fw(-aJBU*yt(FNeu^WHKEPQR-N4b9QI(3ggSi1_v}lR5`+5PY%T;Pf}oCUXsI7<>NQw1?+#Zd?;Lrz4$WV z`5N*{(8sK*U~&QHzVa!i7?ZoKBun`RQJTBe?TCa~W8q9kVe|s)zS??H-Pi#;2>$0m z?$pob8a?*MkCX%8dzD)htopY8Bz+>TL^&!fmkA4Ob zm%;L`whXM$ncw#f2i2vp?e6qxYC3!W`9k#OdK9skpx-=7DxEdG>M%5)6two%B=>nd zI)=pS@TV~t*@h1^9i=ec4zyGdoE{d@w;UzmkqqN{b=$p8xZ+(e0&A9&>kw#rH}d>< z5O7-eAMO=d&OvP;lSKJx^biqpPlGlMgyXK~eqR3F_93MQ_+rjYS$;kxselzO zIOXUFTx~|K{zGf0_=URX^G}?e^~e_)n}|74;ty%csp_}ag)eU+zzewpmA4kOpD_oj zrE>VwaL~S?g#>mJO0Pmwa~piiYu9K&4si0{Eh<#{Z%D~b&rN5|wrMh#KcInpedoS? z0xH_P!TfA74Ie(KNm~NdmKV(SOwj%I#p6_bc7p^iP~HR}%l$Fiz2Dk2SBNa@M!}^p z?IVB~aOR`!z;u>mU&ne_l~A);?Jc}`9{ST_gS!AP4nz>NlvLii36r`6+~*U)`^%im z4B1t?#+9S&q}Q@KIY(`bFK;LgX|R*?_S@YnLVn4`ThE$M>YN;MMrF6vopJ1uVe8Mh zBB^8b>KV+g>q2Cyy?g(bv6oP_$}YXr=`jenE-DG^V&EL0*kg4zt-M%%X=Sll5jqd~ z*^LU)t*(-`k+a$;AX)o{N3{%m*nv%gJB2N-@d zc;ReInAqsQJ0(EgpZbF3ztK~brPbQh%v9!J?a-E`ahyrvPy-f*gO&61#1VVT2u~a;grY^c5Lm}cLBn7g>z|(dsni4 zzlVE{OT^cNt@RP(o2aHNrk(>GH+$wT@BM zkM~0RiNAHix1`DMnkyo+iz`JGZ%lkegDQUv=s~5YExf0ee*RHYwtO7u+)7qc3!Tb# zaz`tH7j|0ywjxy*!}HW<(|0&}@o#UDuP-UhR+r=W@GP~Y9}|>lqP27YktP@mn7TTs z@xr0}@^}9M2Xrs%R{M{E!7>lGjP&W1_LTnbf!ta_#|EP6WXl<;I9d#e9Kv&xGsBaz zyRXY#Oi!&Rt*$DraGFEkKla`{OsSgr4Agh^aIWBHr$|y`z2*f+pl}v|X|>(_KxO0O zEYW52;wI%$g@UFiOqL>7H4lTjR;ZSTL66kbl5$-WcB-^I&g>?G@LFV~uuD<1Tf#$z zy!PV*F8w#P{~z|=@jb5hix-|ajjhIL8aK9+rj2biHX7TuZ8x^v*lrrzHs{&>p7Z+` zo>ynCxvsp}Gnv`U4FQcp;O^gr(&cNCGvcq`pP1fsT2^ctJ@Aa;e<8ST2f=TD3cpS1 zE5fC^%&Lyg&x@8?nB09Rd%WhyY`F_Q%4gz=Och~EnYv*QY-!@H{?zaVI?N&0_I0<}E&p^Y&P)jyXjQ zGthB3Q}mx}{1saWO)(Lp+SYpDjisPFBMzn#b76qY0I#0^kcWsSbl6%}>oe}QWRl{s z>2N35aI>4Y%R8`81~SXSl-y?5O8#Zbn9EkxXGmfnM!>JQ&P{D;%rXdNB9Ug&wa<#4 z#LTUNe`h^0o(m1CZvL69FxO{%Z!+)KPi%%r=^Sj0a9aerVX&J*qcBuop+6*W`*ITk8-_`X>N*v4IVjP^Va%n5?v;iV)<_ISPDGO zh)21(kC*zEe==kur--05ir&sc`NJR5Havb#Jkm9iJr!}kl=+;X_=NKdhf3m~T*6 zKX^eUg?)YC<2dX(<6SN;^WTY?`W1drp7|>?Df04|5QO;~=w9-E`EME8dR0Pd%;sS+ zYjpu_;Yss2p1TcYA%MG>*_G0X@>eSN&P+VJG~GL)Z03Uv-I`|><3%>&W=}a+kYIg* zDA;1=V4|R9{})ndEw3A*c8S#|zZjs=-(`G)M-IAwJbV+NXx-Gg19@6@BXf6bcgSI` z{Qy#uUGoOSW_29VO3dRr3E9F8z2jM5Y02&Vi|{s6iFSrZ`=Kt4}it zufR2hdG5=q$nK5VpAK)F492LHStRi#zmyGl`(>mgnZLi0dVYp%9kB9ga^ogl1wxBs zlYaEHCA6v&6UPwGtzCD`S~pVs{UL#<`>gOYq--Qt&2N2c!SAyQxC-G289-VFu#G$> z8;59f0eg_nip^@no-%CbOy?m!o#Q8%_pO#E%1AL4n8N5Z8Q> zVrc9#j(q(aW9AB-gfE_Cwn3E_i;1WC{)f`}@X&9xePl3OvHstp{Eelgx-%y%b`p{t zp36^K(Nym7R&0kCYR4!)E(F)xaYd4pzy@n0GKO-yj~jD=pnv+A)z(k6y{!JRE32Ix zwXQshCn}Gk2cI4DKOjvO3}p_R1a;(uJpa|67&cI|XPY-cUSd8wKZuehr&FH9N1K7% z(|VA{=6L54+%WEr86WF5T)BrC@!M3{2zc1G#d*{GX+&jl@rG^C{tjm%_-gB`yCzl6 zhV1&xi7u4$J3Z+>&=<7nc>Jf%9ysNgExVkLBxesl^zF8E^uNVNPu^oOY9t6rSibXK zs(QSZ3ETL)M2H_jaEQmGS5|&0 zBrL3so23W>Liv(H-q<7WgHXED{%)pGiLn4aaIP?U0=Kxw8EPTbP<=G=bq(Y`+mwtW#c@9&;# zN!f^qt)h7TOQP~7Eu?~d`TGWa)jJP|uyklTN@|TCOsUHbRau z3F8gX?cNLfJw15^P8EYSD={ow#gOF`IM0kK4C$}NW&}tZV zXSQmihn0Z}9?Il$UJb)6K#7dv{UShvyHI)INr>_`XHBO*A1i#5PmjZHw8^GGSC;8W z^f>X6>~wu7-6xUaJ5MshcSAQ1#)_&4qjGPK9E~KLcL2#{gS51>>g+#dpt&L zlZ>_efP6l_xiTDm#x!<+>c}D#PE7@5sA6(c=rHo>`BY)09n*mhcI4FTBxZh!AMUDs z;}wBMl47(B&lJeZ!cXYWq*vYvXMj+-hn0#0GMUm&UJ6P|bvX zf9b!hPFEofrNI6JK>MT;YXfLH?9QnDpCGj-)X0}#{O`2l2}@h=Uy^MP=I_Pu*_S*? zcI4LKav`g+7%uN$AR^_4TMib@#2IY)NfgAYbTwq0mMr;l0DP*)uN8q=fM~0MlN3#P z)Y8HlMz=JzpVcZX=BU_X$_LUO7M7+b%R?Vb_xKjCJAb{HfI)*UN}Z|xH?te6_A?~F z33L7NI!EbzsyH1MoU3`66Jp6(hv2Nzwj~8weK&jw30nAQ!#Z67y?L!iUe3_Ly(Wg; zx9nN8CR&qJ?EV*^5@`pla?U$yIF`qE{M!Sb&F%F0M%35Ie&@N3~=)7nd zFHfcc_1}8T`HYS2^mmN6MvPzY>zH_H2f%LK{{VsSErT0ySyH6>acy#btDR>ES*P}r zpr<+fEY46khCKgm;e1-82@zL)GOs6EsoSyD za#I%Y>Tb_pD7M`sUmC0eM|Ymo`dtmRV!IO%)kUpwP`#|NEUnI0D}VKs$*%D}JgSGp zn?W#t{ArA9=OsC?d!@)Y)7cpI9X~;7@Rt=#0IdbZzU_X6*_03AA^*0&0Xg&;{udma zCMH%AP*Wq`>HEqBqdPta`a}#nC=7vesbQHPS}W`vP0R&Plh$IHLtCn<{KKPXmxX@9xbIh{Q7z6l^i`{0+Vy#MRVk_g zTGmDGA3qELO`~5;=nPgeQTU#F>mRtXin4IxCgJgN?DT(1es$F3!G4qxH~yWVO)8=s z#kR0oTcGT8b*j&C%Eqe2m~-yE^Itbca?VT)YSSUmyk^6nX;{S@2S5y7hFvb%)a-U! zsK37az<6XWO#)DS2%tFQvBibJ3dy--bp!y`goH-{h>=ow)oxTpnf9XUoT(szG0fqt z*v>A7(5?c;Rkyi$m=(8XMeRBszX4=?zPk+guY=3*g@2#CXuCZ1uC{WDA%;S-4tbCJ zE=w^Bc2K18J6tL9kK@?!LCL=uvxz7%+qq<*uo5mNJYi$nW2M6`TW+TQ+UUdw(;o#l zZ_Ff*t_&Mrwjho`+U(xmw%@?|3RQVrWkczTR+~4>d0QSI&B4Z793Hx)jf<5rH(qVHYGZ~M38wD_s7|APH|9<@n79R+KD^!_{>LpM0$(sFmP?!n z1RXK}XSuxopy8NWo}+lCtkM(B?@f4owK-UBYNuf8Kjv>u{+*|)(*S28qTcm>4{iIy zZ zF+nOhtn^CTsN%Uh`*uVdZpoBGWmtkYKW zGwFR7o`zU-NaOIOI7#XWl30?wp8%q&Uxl@}yV|8E%IC=qs;Nt>|1u_Yk_Ly<`|03; zX%#eWO5Ty#luIcxg^sHnFy_939Ow?1<0%tdRQJE3QxUTvAF|4aOzkYzw2=AKG`lLm zGD1z1e;p)Djk-z|S4IK)ON1W%&k|#rF9K#)%u)a~$^PTwo^I_=Ae3AeT5o?0TWFgGxkYWLo>D*3-{tsf(4eso8EflW-7x&(aK^N=DmTL^nwUX8c)L zEj>xLoGk5L}f*%tSiR)E+z!mC+}Z52ip;}-#rwo zd(&LcU@cx6nb|y{FY}gxzZ2n&(BY#3Leef@<=f}m*oc* zS22R-ze7A;PvtFvd#!L(MQr84Nz9n#`nnX2G)EpfGMfHizpB{%Y@hdfcQU@Fz1+AF z(!5?@LR=WoX%>ou#ah1x4N+RH=Q@EDW0!1hLbbObW8DyqSW;g2qcf^Jyt* zxn}Q_&<>8KI&&MeyyX_EdV)t!f&(_UNGXk3*@t$CAG}WYEx_L9t{t0Qnxf|Km|Hw! zVw*9?XX@4n0AF2_cU-F?e_bwWIt4b4=L?E+hlq*T~aBr15WEYz8;Z|GG*JJGnC4;g$5Uh#}#BH z*UjuOf8OEb3=@M!%OVDeF&ANz#ZeT8M!Ag@;qasmo4HD^Yf8`%mIGd9+vLwA6>FwqmgyIips`TSz~>^W&=_M#}vlKB9*zQ@%OeD z4Uyo|Ojq%*%B04}eZaKE)lGTr&NtLf(wu;(0eP^a>7$*DAmg%Bp*nSTf4ubp?WtNTaQ@E2Fq|BJp-xI;@ui#un zKyWT;dplbNzC^S5%#WJ#oTOI)Y`sofLf(hx+PkdWvZAKFMCr8h@7M^xQbSb-X(Hof zLyL8*XC6}ak4D+M*tGl&2;%WH%onZ8o@9C}v#$q2 z;pBM7JknxCO8BNzVu2{|GWV10Yln{+BO}l0P%>4M_gaMSc;!T zM5Dxt6Xo2=Fn{%f+Tg>?bXR93RnQslo2i$VvDW*Bid^@KvS{U#8NoE5vqkV6Y}mAX z6$YM;?&nurn`#QUBR&ph`qMB2zY##>w7SNb{Fn?vqsk=ne?EMBA8_FzlDf#UUb&UYqEyQS$s$cDS%^S&&-B?ZDUxrUes zg1GHkf0K=7MN8XSpJY1p zw57ER4s4Jv(3WsE!N`yxp4FHb_gy+TtvzC_i5$5zX13qvzwT)M&GhTf%TZZ!GM0Es z2J~)^-&vdh;ZqNCIm`G+vukPgGk%6~L`<3IADU=cYGbNU__Bu$Mx~xj* zQW?A{)HADzgAPm~QrPsU}Q1~ABjgR|5PwoOJCGED3@YnqM5q$_KVu2ai|+O+*lz%#3gY80H2Jemiv zzC>f!E^}vs$Fy#ok3dcY5<)ue1Q=hVi4scTciB`BDQFCd@Z%_U7siZshpB{e;OS)u zU~)Po{;F{#30d}@V!eDn-VXjy%MaFm#$8ky?*jYOUBPL5UGgLHc>U*}!JdOzzF4?S zdii8`ayQo$690=f)m<+Wg{V^MGz$jr15L0Acj^xgkR#7&JH|#0qs_}fa7CWwzCSdq zFXEiUCn;gTvQ(j^^f!aJ2w-trZpn9cl&~N?#;`yp^#I`(#oo?!(=xl9?Sp^5MJy-0 zGg{(83QpBww3hw$M?NKJDgpfG_p;A_`l52-Zm+~Cv4{p0Dwx21u?ka&sD1^^TDxO=l9X7wPLyn7eA&-xE_0`)T6Zk&%5H~cqT7pX;>zc6r_~!jq)EmZK(_^pH9j?NhP=GVDnK$PM!#*4BgUiPwDU* z{!&ojUbDMvDEsm(lu}Y*jMav`*j^s-8QxnH6_8^b=`(ydvZ_A%Sl7D)_pQz()|_0z ze{@uhN(ya4PNAlJU8+GVfF>m1TTwwwFHEKJ7zbe^r1!E z+;*DWA76~LSjoKfx)ZQw>axI%8aO%?fdrU1NAn}!VSNG!D*vh zwF2N9@d4ohdd?3AT#tN2Y@qQX2O{dqOAzqu8OI%aV;r9&f z-SHW^e$CBJ6W>l4`f~rLGSz+WA#WgrftY4ynb!V$4gE>W-m|&qRn>Rb)jiZj*pNtu z7@qIRj@oW+Pf$|-c?1=t2uQ{UCpyg}EPtJj*{x{J6(=vx^c9>4u~@&>tK*JnauL+c zdXT`zj-*Q6@bD_O{M@M!r(l^no3-1pPAC=`i4nXqa9mxjxG|U*j11A0iE0&^_?GJ2 zvXs8pEo7rNZK{v6xgD%cBqZ#c*A}niHP|mtPFoqIAe>d&H}LR|))he~@5RaPypMKW-TUA6s}HluvMee+wX zTwYH~ACI6GKmD^aw2(0lV|r=UN+}T%L611{Lsh zp9?&c+1UyJt70f^nSI_3nqIIx`-lHH88!I9r;;T~64qRZ3T&zvxgmGpP^*3*rlD`G zkmgppVlEkcY#-$5S?g~uXie@nS`U}GW+ikbo`+AIQGw#wQ(tIc>4Icv zveUccUbco_Dv6yzZP@cobEkfc5QWHP4QqfY=NH|Wl|SGjOJ+=%G=UK-F%}aUOi^C1 zF@{}xvl;V|ut^DK+Ti_B+QQ4=2{?R?Eu&!8^5HA2=i2Gudm?u7^nP}d9#in zx4W=bC~b2>{(OxN7*aCw)n{zZ_m`t%JewvuF3ufx+UQKL1(>jgiJ)-U$4NlZGF)G{ zjnDQxHxzK$kljo>mx8ffkym?wtmOqX*A8)^``eW~`552t_>>wOcN5JxF+9BWAHIbC zS{$M36?{|KqyHe#DIA(6^b0QpAysB}F@6wP>sn79`y_vo^1Oq_;>kHWts+SMqe9K{ zcF{C(OmOvvU^Hxi9~y(FA?ChFPz3Lp^{8l&lqqz__1EFs2SD+7xkzm&B8#OzYI#`v zyqI440tebjU|DZ4zb64jM)H1P%>d(F+?d;O-*x1j{)hmikJgODA&F~}6cJ(UJpFfv zAV1-hBlqV2Q}ZRwo*M;&lkw_3@TiK)&4KbBGOeQfh^}$=7>X(QDh`FR%vP|i4N&io zlK}-SuNWsMT}0gbePZ*kR>2G(O=}1G(v{UJVz#Bb>@ywO{9y@*Q2oS! zhb#}cbDO*Qg2j>fV70#m4~@gjoK>1THmH8Zhhn)9N`ZrGA184E++ugZ=73PpV6~QO z=}+7BK43o=l?o_C_j@&!6U~v%r%9AV6JITkl7P|nNQULgG6e-geHv%n6fnkeI8dcO zl#MV08Vj7SO$W~Rq71JGkKt$^E8tQv;sLmpS}#;tIYqxjX^4nZb_>x(w$J)UKx_gl z8RAuIxrrTMF}358Y{vO>Fk=VSNoYArKe}1$JUMnSRtJlp8QWVN z$tp=ffS2UztU5Bw1-7&}=>jrw^kkU%hKR@ZWt9!`{g@lvI^A*WUb^YE{FnWM=R-z; zdOf+hMwGk)G>109(1o|*Z~1~S*3Q<>!D(rZawmM?zAu|q9}jZuZHmjj)w(0GK^|Gj z87$8}Sz3KW7782w*Pcnzds%%naeh^64^hAf6OAGD-rP7PhMj>qxTWfyIU1!|YBv$b zK;`EOFM>r#z_r*AW-_?yV-#U(=ZX&L;s{?Di)e>WGA2^fChm9X=JsD0n-Z*N%tF7+ zSQ3?&#G409mG?ddUCHSHXMIyl<9T%c0UBx`=nK)9;^V#Apxq0ylHDX`>G|VuOqa0k zxJrS#Hp?0nyLQ1QP)+l?CReQ#fYYmr$m>i(ZaYov%bz4@!%%H7RH!lWtS^J}`GKiyX>1ENc0u*ZXNoHe7WyxB9$QDTrV zlzLx~5e~{?oob9?Cpv!p3kCTN?ZGeq((vCdZ~T-l&|OZb%lwJ{MR2toY4)G{9Lz7}e%e1T|)Tm|xhh-eKcTDlc+68mM?vtrR%F-gNlX-yttQ zAc`8jy(8E0r*k7@heFou;7REk=wHvJ4f_A$9g`z?zj+oy7Ze-(BU5h2et2F@_O*L) z&KqAn@qUVv4C9*L5ti%z2q0BTX~(ep7iGZL3JBH+<;m1rjyTzlL_|Ng1}gV02{pwP zU~Y-*4Hx)0QzE%m)w&eP+E4)bzh=^CVu02Do+R!K(0??HOkN(y+9)m^*MZC}J%-d7 zGLqthIz6iNm=ik5l!bFOAAwF-p3B&qpIY9&)J7RqqKA;;nY`U4s;lj7PdFhHG{sg? zJ+VDlUShwqFc&&N^)DH*QvtX(?#(f*axSm`U;*s|jrwXVvs2u%&wP-MhZjtYtpETi z+wWfx8LODWd(xA>0}XuOF9a^Y81q;d3BV{821uUGSO=K>eli&3I}IfwA#9Z%*6Kiw z;m*-B!NUQk3{#m42QlVmO2@NwXci5K{sLLR&EH@ zf}&5!KRv)Z2ccUIMpNnw7f6W}Bio(X;OM%Xvl(uBIeEMtiJs*9Y^{-fac;WCLH~os+-xSYh3y^(b9-nOB)lHN3iBpr_2gF+>(3mpTIAUk>xlI~eA0 z?JcroPLb;|FJMr&Sj%ETETQDCL-Y8Xy1Wy45JZ zY(a>hGy?B>nx?5Vwu}%b8}WD-5f`4(TIXd7dO=NMJS`f%U-W<|WKFumFTDQaGaNy! zTPkh>@%}Cd_{RZeVf+#m1dLt`g&?B#qdX*o2}zT1>`w#BH!m*Ene-+^$a(%*nvBsl z-cVCr@5`q#3Y<~*RsjurnQQ|FGIdVtbkb=#4_9|D}T*K2<#h9e+__?2Xr1 zJb)@MrW_me)qWV<=&Le$UKPac4;o4tjq_~?R@?SQ)5a?mtLq}7 zQh+j|zqLh%o`eEKHOnkUL8|Bb$5hX&=DbPbdKda5{PB(#{z&jMap?@P){ux;5I3+* zW4vd4p>&e!Db=z3fT6E}fE*Hu9=&w@0f0xk9G+WbYUj@ZWFYTXvrg-J{d?lu?YNSY zSm|W&K@7Dx-@7)$`oSg5~Waa zMBg#Dbp#kd9((0Jj%oVHD!}|B1HG?|h)hf-^llRs!3wzEm$t~posYbL@xJ@D0$oSD z&8Zi#-N^x4xCs>sn;$W zb;+-v<2=TR=#WPLi8+Q$EUDnjh#1^7dQ@_gMHS{y&X7;OQ)+P^W9IC*1W7q+r_Zry*cP*2tx%%J%RD+DkS0G#+2 zSLK`&`JL=Az5e4$3ecXnwWupD&xq+~`bhvcU7cMn?qNx=q{AJsFJ4sM?AiugG(bJ_ zr5I{4iV!F;@Ae?El+sD*9GO>4tW6ACGHEV+YF$T432G^X{FO@ zEQfdw4*oZ}5QFlFV-yfS=XBQ!*r!sr4oFCx$#I$=Qs-GWSr+iMmo&gJrSb52Z6@nO z6u-~_%aonVI;zV_RIERPcz1R(p7`>o z!$|@rRP8!izXiGkc$kQs2|m8#o;(}Wd*Vy7Y@M zNQ~WF(Me}CuB!uQ8#~|8Lp=EYcnnA6?F^V@y}h>8*{+0x9`B9ULx%#X3V2_Xe7Al z6_I7;A9fV*0cQjrfwPDL?P)X)`V8a%DAtS&T`Y7G1Z@iPKlH6CpPrkWuD3tbG^T%| zApeCGUkLcCww#Y+DT&fy3t7l#&9D67i2yullLD(TOBUWrm3-7NT$HTL;SX9wDpbmp zC8{g!-7anB!7whfC^xTKLAkgu5OLYQz zlDm2C)W^p4kM}PAa*^|7`Mi1(*jx=UDcndCX zp&od3k&eQzUCRM>WLVH}q-WqE;)Z{6c=m%w;buJd%4QHwR!sdBOQ5X}UVig?CYW)U z7^LV1C*B|gpO3k<;sdXCasUFQVUp-y2ib~FjsNAV8{N@*K!a3!r-D`hc$NNLsSROg z*XFf;OtDyK_^nR|jG^jyIau6EHlQSZV#xm#4nwJZW#m;988C)*4uS zm^i*W__b#_hj)kSmZ|d}=;$*rqxJi}N?Rnch*ppp?*UO1`4(HH-OzC!B)qnd5@I(u zRd4rYK(m|~!PyV2)BaO5VgjLsgx#2)Fq*@SE?`a;$$7Emh_U#ApncWd(|sjp-*tH* zJvk_~wQ))98yi7b*n<&R1!lsDjt#xuLh3=-KI$OJj&9%goWR!zQhu1@hyqd?qfzu_ zczxHWrK+YMl*%fUxP8rUn{)Wy+->P!w>O#M@c*LlX9VtQA-TLTfLaRU4z+iOmtRaJ z)(Ad+Rb1Y^3|E4fFRKpv3mSnbHP86kc-f+9;|spt$hcuQZX*ec@j;>biyVpqxWr>u zx0Jw)A-q%WM6EVSdxlg1Bmt=l^OciuomeWmauY^y?CTVZi-{>)EZ0JrdNHu}87nCh zUL02oA<*;RsjJPUdOk}5*Ol$SEliG>;bA%yC-U?U#AYNt6>rB_cCT{H>2I>b^q&^6 zq#&aqRF+rPk?teG&D%7eG)&$vPpeA@iBCW$$#dXQw?hIoec-)ux%$S3o`jnMQUgp* zcdfk22b($$&R@QX8Q}{DI$W7RSHBbcXMp?8XJVr;LVSXL=Sjr!`oYagG?CwL`82!8 zH*C78uCgB3dtUUL2Kk8LB1pVZ!CSrOpg*sIEstN~;k=`FxAbz{GmqbpOYw9d}()Mlv2XBpg}>0L0jinkjeU+TnT}X5jBdz^MqitU7=Vaswqe{bdL8EWNZ7D|1KoR zmFIkLoOdH2J8FfQjl9j*Rn?o=ul$`Lo?0#CbnyH8HIxEwSR?0pqL=f+5m_|`sVWn#kKx=g^_U^K zUpu|I8Tyoqi24zW|{$g1G41CGXxq}xS zy25vE@~o0R!Tf~Var%Bi+7BaIaKb+`@3FIp$d3Fe;Zm{?z~OmCrbr<^AksEb#80nK zAYtd;TC;u)r`Pe>1^WJO$guYT2Vy$RPY=r$>02ZULHZzdh}E%+%sCc*k8LO;xzo%W zLPn@hK3X6#iW-`AhE~#X|iiiyufXrBdOg>pGQ$lgK%8apnKHA8?4TGAs#K z>A=k32NoCRQd7s`F9*!`(8+&7N!m3<7o#SO;OuGKr3G%c@a-HP+66gQMp#NlBn*{; z_m+5eXgvt<9*=Ms)tQw1&kFz{WCy!x(TQGFq$YgLA#%$Bl0>lZ#2R%JRD`M~<9+=x z(&WN3vjTEiskCEUhaXvj?I1{1SZYX&72axiabYymnxB?aaNxD8*W z_W5u+kxlsz3db)cN^I0q$=dq=&CCGvaNpRi(Ts5crNzPkDQ$;0_SgsJ_%!!ui62+^ zzNgg{GgGQb2&GB*R*bX-QiubBo%;iWGvU$BN*u8#uDi+N?TJ*j`><0vP~hvX>Up@s zyTpMRcL<3&*kM0a_}P-2us>+C0k#wiU`gQ>MmWIbZ`Jj4a*0KhL}-a+ptFhjw51k)`J8cY)_yW9h40%*Tx*MF#%=FuDS&``Z)q( z8HRy9$Zm7WihzstcoPaY`70O>|oMGphvJ#>FB}QP+^QU91;UN=4PoD)Y7cw7VxK+DEP1p#*s+#CnWGp z+tLBP8I04u8HC`#^2_dcSe8RHKaj=Fv0eJnkDw{x8h+!&uT7Eic9i>`;ZujG^(=VP zWj2}TK9sSz)*>%xwapG6 z#L-7;`2<6U944MEt98Bu%e1_Q+??8q_wkLq-5ifhxXUBwsdbmKdQrd(F!=_R_4S&w zciEGQ@GeCN7*TVCCFAm%X8mAxL<5+FNWH9hS*QhuUo?NptYkW%_Z|tJa8DLbOtZ|H z#&9wt7;j%LPuX^0`Lo&qUElVXhTn&#a%jI-yKZln(z#)c+XOFMr}iqQ_>PT-n{#qb3}htA9j_N&k0yX-algx9I9z=5es zR7}>wJaDBc#6n)?cTWHKxmDNxl(Ass2C6-ash16<9Fg`}bN@oa2Ln5NF(Bet5gEK8 zk9w_ve5UNU!vcJg+D-DRDNo1iyy^42y^odcIV=Ayu{6@;PTfx(w|c7_bYP1`qvZIw8T%9PAmLItroQcU;9T(Aq-)sAhRsBebO1^ zIHgbY+zXqp!>AgXp*CTO(%EZ=Si{N9K3WT3;3nwEW9Zwl^G&JN>-= z0HP%65jTCs$gie7d6zu=tf{sdroQIU2ChfW3CZVv5V_p{6swQ594K zc1&b&;cg8S{_x5nz_WET{$jt8&r zbTc^6i?6U-m2w0Ewt3-GUeM7B5sG8IPN?KH=MNgq2iD?;F8w$rz>Tkp4_;5(iq{}7 zPDzTB=W?_Nnflo8wCvDo9Hlf|k(KHa$oJkuFUq-}iYex?$!mGNL_ z!9CM}95s~yYoKU%R15Ni)H#4u1*XW}*gS*KuufPNXG5CuRtXo+(a~%uX zD%^h4`#z*K`^~y5Grw1sq!`I1CCg!cE56M9LY6tSy_uKOp|@9ntYDyed(WlpCv!u17`w<<&4 zm>50|SzNr&0xu81O^4wK@vwpSJPJOG?}K+;|41(qq^H)DbRg*PctW^xvAafH@A?8Rj(B)BZJ&SpGsMqxJ?s(YAbdepr2}Qx7 zz21^RbMhfL5QPz*QcQ(7^s(0<^DIw02m%4}j(WlTDs3Oxg*0FaW^5!BY=e+tVwBEa zJNA3nZQsQ65TDfW`B{kGD@QEUvX3u%Fdm3WWGDOV1Dq{-M<*K?<(L1rGek45i)a20ipdvmD&mFr#*b>?@L!G(Xz7rigxo`Q1A^p@OegMba}v;yBe`T3^b)o} z5K{r$l*9BA^_#%7B+e`5WUbnl6Mj}((Gh>2-4DPW`Qe62#Xsx3@Rdsli;wkum%LpWMqgg`^{X`_ug6mQXMHpmD@C-HL)z3?U=2o6>9r2_ zD|GwV3@~I?96O`dqMB23Z~JgJv)?;2dj(0CA01_12_$jfsV|z+xTtkwyw$4xEw`7D zV8Dt8gf7_6I&WmBDiJa{N>Z0d!plWcTbYlI9UDID=b|(C53IeHU7^4~bi9hV9B<>d z1?UEPV@&y`UF?=m8-I=*Jmfmz*0}}Qv4lYJel>Me)jgcxiyCD9{%I*tEaBOH`{wtx zn@Rd!R%m0~&P?XV672PNHVSKRwg3Fxo8`bUe(W1%g~8>wUFYbtF~Og zTIMtsMd%65Xmp=>YGOxA%ybC$vY#bqOU?9s_{{Srkf?hrvc9SJ(*bc+$>!@(eo0T* zWXH+_0U_$fYj=Uwh)+Tm4s3UON4a45)H_i}$@*ODoEHD3&Lt&Z{l%z9_crv$)j69W z+xLy0tHsQfdu)Hx&!dbUm|bqD{XBL}c}<@{>a?Ho9ItNdl)Z~Gs;4{5kUz3D-R7Y5 z7LYKQ2P(}Sp)X&FOm5~F&XX%^w~{Yw7;L&3(tM1G7oY0kfAfIR*$4}DNd~^k*oZKV z+c{k30@M_Z;MbWnRJ?bq>#Fz9oxALh`+^87`i5EFAblF55a6AZ8yY;q^aRm$W9xwq zuk3C))cyrX|58)7hT!Kz?WR1_-0fqP%gOh=+D#IW9UuLk5|Y)Ye6w>XAY40oo8aLj z?l2O4?sQBxp^gODU>>=)&WdV~4JB^GoI46v7@ID1KF_FL-W!0(R)Q6 zF8cx_rsf0e($P(~gif`t8xkmL9!D@W9Pr~tB+^++iX4o0^*?bqB`1B5tV!0bAGI|{ z6r2S8?@d*AASel%g`?R-YEp#gKfxJ~BRX(qktmo$U5Nd}Ci@Z4K{+n6(M7{k#dH;W6m6iibu=|E^^ei$V!L*)V;Fx)eeXH z_x2VV-(M6m#wYUXVR-9zQ{e+=Wj!OF(BXDCBc$naMd+U^0>gRkrHar%H)$|nR9riG zMcz>Ywmo(;#TkmY%z9Ak7p@$xS^|ow!=?Gr2Ow2A7C1yrcl8i{+*)1vLpLRHwd^yD zH?7!*9Q*fPB#bSfo{OyIS(Lua|32-I@J0o`%FoR0=0w^8fpt~M_Gm^3b|~Usp~L5; zQRapyGxzwZNiigBhZ?M|8D%Kg?9@Y#mG!n_lgaU?5pXhj?Ru`ctHhBupZj5$`x9FG zZ+;FaGKfE~-%R(Uz=&FLEa*VW%D_$N1vk*-{oF(ZRz7!B;j-$zCRuJ82HvXwpqKyT z1>W;oYVLqZjcU@?rsjDarW73?-g^-PpmDy>GJpF zEx0Dt>Yxx+{r+xm{}5Bvp0=_aE{fbF4Wby=H2w2%+4fGQM{V4`(L;NcW(pYxul(|w z6x2G^1RHo;<{(|c=go`V)@w;_r2JR{a{n%op86y3@q?&COdFQ{9));xyE}4+hT!wY z+q)TNDxNQL7N>3h(xr}{1@V-oeTx8Zr57C!MMX46`V;o1am#BosV!(iOLL?;0W2Y( zM#q)f^(@Pj^OkXhrKs|iNkzLn$6TTPsc~oiwa-= zRdQ@^IPS&`34>rA`D zeQx-N2;%`rz_wzWaIdb2?1o#bJxjxmHyLnrFWt?)v3G~tX&F5mF1)N@=b_yK%Pa3{ z@Y}5xmFacTm2_w3>cbhW#Ga`Fs@j9`1KN14-#j}(>)Qi0U16Xyk+0c*JrP9^9`xJg zVcDspt>-WgwbUCiRMuILygR%CQw$|NsU8frFGsbnUmTBs3+0l^yu7`nt+;`czHIJL zQht+uY2d2blHvyYWxfcV>CkR`HE|817iy(Qy=L}TjLwvF@$Apc5G+3z95QW1$hzAJ z43S{?R`c~$K_9B^JvMxXNH!_n7bbF)qn$Q+6@i@@Vi2Uh2NewORuYjd?FQO<$z}32 zZeb!$Kfd{aT}eBfcNt5`g{?8PD{&%#owYK13K8hq&r$dw?cCalSiL_<)Y-N<&2hR| zAFFIEi&dn7I64O%LOz&~bDs%HULZy@mhYv(j3^We-D3{a^G4A-%dA0 zLV5YEc(tKTiDw~iQy=8SB$bVqPP8zRFM(w0Wzj?-2lf^IMZp&R-EWgGrJVEqFiLbonB9g8BTfT%lcT9;isAs`VrKbx7Jdz# zEoS2;hd4&GqVD+qyvpLyLrA;mJ5_fi5&El-<>A|&jDoXxE_ge;fjASKfeEI&_!*XB zsk7=MTQ>MxCZC0j~KU$RLV zAJ{rJP#|53yQ;P-x_mzyXvL3CE0+xAB^J#n`h&alK=!dIfyT=s?U15#UU5YPltB?Y zu3Zkzgz2*`S#CR%n_m1-sS`cyy0-AbkcnoW_5$ybyiB}s<{t-LSq@3(G6j$Dqm7r2 zHb0cea@ZwC7f>AcXu(g`oE#BnWPpV0qUf)k@{Rt|8d1izmEkeFGfWC``az%XG^F|) zEcuG(SAjPJ&%0oJauCO`Ej%uoDf*8dOr_!4*Q9S_Qa+z8bFR!0B_aFi8ldg@5C@&s zI@OxIF~UDj89CeCAf{{wBfN&C1-TXJJ41nLZ8cVEV78mL!nt6Lr>klg%&$luby^ss zw~akXm8Dc?Kwz_~8BTo9M{gekIYtC~P_ew1SUxJ*YP4=u1*|B3F-VV}@}CiPffzRQ zD?^V+tcHZu*30lxW8~`+ACA~RCIup~1au`jx$=eJd?KQqi{79$Ry$>-%|i^E8x(lT zE=k9dW%Pw~f@Pce!|PCqoj`_{Xnw*8VD- zsoura2IF7gY}tc~lP_R46ym6eqOU`wzl|AAsZID%F zZlt~Yuv|;OOF+-bvMs4r;XxNjQg_`6K6j4jOAod)$ijjCW67#n%kRtT0U(A|&r3mIA zxbbR7`6DC@*aWN}6*>J)Q_2w?{l#NKU2%M2o+uswqe!%7NbGUgnuvG^-}j$RVQYg+55&MN{pcs9bbHMkkVzF?l>t$8CjN162@$^C_e7kDVv^Vzfl$%Ih!L? z>%=6!RF{;4J#KG>9J-^lUVrzkcf+tWB2zt)DjvO95orkT=;cHdbAO>g6Oujdm9Edq z-}j-|z-N0%M=5O_q%n|}{?j&;4+O*+dZYAU2Jo%hAqZCs!uLGERfk~_!zD8hgacK) ztdS(2cj7&|=8lZ>qosRKlgV{6X`0W)P|NOH%EaFY(iwc8s&B)D5`Ca-psHOG{bvBO zz{ch#jdADAqrrJkMtD+4#DP2CmH-A}nHv<1N>8CXsrkEuofawS8&+5391FHv2LMva zosvGXI}AB!%Q_y-hfu!%KK6Im(ecn8K5T2r$S!^R8N*mTCd!ZxCOMpVp^feL^(EvO zxOEdZ`TJt;z!CHBpB7ZGC?xxZ>a!U)&6iRH!ZDzuM6@+0wn0NgWp2-XdD;e(u=PWE zvz)GNAl;nTJT_9Q!Mfa?S|=~8uK%pNm%Ykyx+d3~_tx0^!rkU2;<0rfxASr%jnFQF zA3NHxd{g+luHf6t^q*Y_7J3(hsevP4FiECRNV)d6eJIyYbQ0Q1ET=!MD?szSK)oxb z6wh}LC&8xr^+5d+S{8id=Up(j{BacZSN>9jF(u{XH(_&ZM-5ygt;U0nrWS zuj^cf*r_J_ri)H)K|e!r^y3#}tKp-;tbKPa_0!%@&)Ztx!1Z=qPwqK6zE};i`XHvV z&_{awqtuMoQYmp37|HKj{~RL-Km28|@LEI8Ckm+k1?&4kJFM=M#pW$BU*ukm{P@D2 zp!8_T?@zQUreRL}<%D};SMEd=*KA17DSSb|-ssIxsnWw6tG2=*dkk_DVh)7nYO+zo z$3XANVSD)5>#cJAK|a3w9=-X~3{!`MF|rom0{w7DOgwcUKS^TxS*HSjcfrKR8 zTwjT^*7<_@F9x#PbdY`qPHof^H;M)D3Wrsg^+EGK;%V-8qTco(sS%=qm#!IG3YO6X zj{X}eweY-b67culfzQ|upVCE1OEv|sVlpC>HX{6pA}T(AE5&4o}Q?TO#eGR()5RyDA-viZ3#PmH-|~fa`{@+4Ks3VK6s}& zraQGrI_NyK0x}gQjwyJ8VVgSDD34=*+pZ8xZN2-AWj2;1w6#H+_gwk0McCz-UD>rC zzj3SB#tzOcPJm)m#5U{Tw|mrO()nzLBbU&A+^kW|EjrI!*e2f>@%cVV;%9#fkG;o)UY?>{&{Xjrip7g17v(5Z?I{fR?@C>Hw=nbVA?l( zVw`%>#Yb@7dkBB1sW0wKp&TZ;Q=GmSWp^C5p*=#j6b_j(T~>0IC1pY0dfXNrbZ0YX zbYWkcX&Rne-aNX~2EgA^p8I2+&gShkKS9R1kePFGGHTXNTf)|}2hM`Gt9r{$Aibd& z{JDC3Q7}JlzR?=oh2@pYEWJVEqCLDZd5@P3fqjLI5IlyE>&8`Q(`2$Eul{Uqca;eL zf-`rPm=&{V52N~cd#<@X;o5Fz+FU_T`P}vrRIUS6POmFJf4g>t9GBl!u86mDp0JBf zwX`>N8N_gPr&)D6?Q>$4%DSH7>(xzZZXoI}wJkc*8nP4y*|>h2lp`$F%a{8UV=)u) zGoL2GB;q9OD;c|FBns^D_`RdE<+r;L%inGVpB}ybTvTSTbNTj{fdo6A4b5A{UMXQM zx<294fD__Nxr^Lt9aio;wHmCneuAOsWUD6Yun=N}8bTY&7tD59AO+`^P^h%f9eTNc zp&m}<8k9?kRN8OLB_c>wD zWdpXB&d^JeuwJ0`n_&4zKbT9we^jGM0K@W}Ozyh(GZyf4$syJ=9HgU(f zH}^D!24JAtx=LQSgea@kVYj0Z(Zp7-a26gYBiwdyo z!NCQ7B$z?GIfRoNj5Nu0)p^ziOIukJ1}5LMa`0>Cbw+VMzXlC1)qkgJmwC3Rqn@L}ECK zcCuq4MzQ2Jgy>u z3wH`$aZ7FOu%g}5&Zoa70~^x)EF1Un*A=GOyBIpzcM+|7^!E$z2;fGtb9G0vmfHL@ zE7;G;d*82hEPG45d60*sEqpWxf*0T2M~8@HRO)Or@E!=S3n8p*s;g_G!Gm$MIozf| zM7WPl%RcMnTrEbQwwRR;<(CfqCymwm3*Qh%kuiCA{Cj4;_Vayb?zCDQKm6W<+DIi$ z6WDXLVn=wOu5iK?lEwPSwtZ(Nzs(UZi#Uh=+hESLnWLhgNHa zMOy2i858-B4~p63ti6|==7zbONV&_8(nlP+x5R~BmXncx`gmjJ1Rh?QN!#8XlZ@|J z)sV+ei5f`o)NCv_;$AdZ%xk9_`>Vyakk1lp_+N0@hz?3x{5HuKlsCCuHjhUd&P*lW zC}UbSj>nf1Js8vC8Va3$-4D8pC$3*Vj;66K$*KK~p}mdtcX%I>0rdu-YrmpUwWUI+ zxc$pC-lMcru)S2gf3PFwmO<`RTBFmPFk{2d6Q8n#lffZq(MOf~##mY6z*?bnc>L6UH_cAg{|8jlE zWC5ionQ3$Q*&7OM{OWLs-Hcb%^2$iX8!M;vc%)spBlHfEELKvpHo9ehcx!38HTRO93T1u#9oS#1Zz}?ARaE6OetBRR@QMd`S*N!poyd0 zR;JCL2AH(@kaJMZKluD=hPti6W`UpIC<@$tL!B<%%aWe6J;y|`W#=K&QnGkO;!M<` zKD17N;4_oe>Fr$TRDS5n@EXvsA4ly%WN4|r1xvC}me01|xp0gcw~EjPV{yR+wK`(6 z6Lg2;2>Vl$HOW24^jA(Hs`Y78RR#5Vx1%7xEUVvR&aJ)5n`xCtO!MA`0X>ll3(L&E(4$XoLM2 z?4Uql`B;F=%qf;THAJ^HCF(eXxK3Vju(6|g>qJA9pP0zTM4;oB_OEESD2y?2PAfVR`m>W_rv3UUeYfQrT6dne7(bu-?FE1T6RZDOy!FFThN%EWn&FYmKgS$ zbZW!&T>a2%r$}QifPqL_&Z3Pb>=Ud?Gg#9O4bGC5mlC8OxdxlAhcQA;D@i zWq{1^oQn)Hz}=K36k=+UWD4d7&#oLMsc9YN^t)qc$`SW?zBN*A_qi)m?Uc2K6|bxuu?O*jB_uA0V6dyS{_`) zF$5oap>@PzHC>dU0FYhWI(X||3SVM0EHi!u71(uB)xF0Yv8=}L%~S-`0X$FIB-16m zpqRkTWdTR8;MqfHMv#dSSKyx$QI!Ej@RLd{jk!%&Xg;(M}<==;b#K2h-u* zeG5dosV;(_Bg?1uV7pi>s5-_<>fQOpo$BHvk;YmYWgh9$150zk-OJkjl12_Ih}tn$ z;1dv2HBnbSPP^AA6V%pVnR#QwW*MXoO z=RQ~efn2y?%kK?Rtqk5Z->wxu9CSB)CHd~rn29vQ`xZasRUqzc3jvUb6im$)KR3mM z%*nBSgy-m8rA!hM;}ZF8t@lqnWsq@$l`z}%s?-|Q+U3LT(pG$&Oype4+^W0e4juEJ#B#*^MeN89PR2&JklCE9B zSW3r)Kn);|eHovgwF?#VRI}NyQyvXD3z=6es+_s%h{dK}>f|Gc5Ya6_X4|k|F?7z^ zTJjkguDB|z?3AgXe9G6HT90np`4s>Xt3SL~+^C1Xi}u!AiTxnahK?_=Ot5GMD)){w zWe*noIm!OAU0ZafWLr^09QyMWUM~IpM7|%?=1eAs%eR8PP|1zOA@XeuEoR7pCkg<; z;a&#c%rm#ee6VEiUdPbdKfO^rw*%*`j$D*)+o{J^7a#+o>162}wZgm@5`h8gnTD!f-*@B|#E&Q3m{OYe& z#8{Rq6lgX2g!1;qR|du&KQqfqHfDi7mD)_Fs6L z@Quh3+LEn<0vQ)-fV?b-blEuJ$uOszgBKXNRu3wYJc?foeCjmL!{TecS5Z#eNw73R z!`J5r(glBJ-eaD|C7#tht#1>U%sPZjv%lW-%V^4KgC}^i7fP=ns5Q&X+;HLm8CBY71prY#e)J{5 zK{dJjrr*921+9wXZhq{m=%u%J(#yCBrBpE=(gu?fzMg%XwpYCmV!KM={*uOb=KP zfWYpgGhKO0`UMbhC_FV0a6OWHl(N}h_r5ljm1U+>PW`35sIjR6vDw0HuZv9tWe3O% z_TicrQEo#{6P*CEBVoCyIdZ}uj!+hAw5Pi%!{22P2B1vGUBO#;?bB?wUnoBKENOj% zG~bZ9`tA80Olj#hQI3=_Ao&|5ufwYoHkTQl-d}VLq4CCZQK6?ps&Mqrly7xM(~Z=de!e8p8*B(o3rCi>&KNRsV|HU6%&hHHfx#it zbM|Z6ReDIPf?cw@zTs$f>bb{X+7IOhJte2*H^h=D4<9VN4{9mc0m3ASMHVpfa94$u z2-hKkV_%VT6{V?pM=Nk&@1ns)5Q5htg?l7jwx~pij8SMXvsjbn@g(v1*U*j|;zvLF z?R~QPi#gm-*+g`GblzY23j-zS)576^0{krxQ|0qZab&V;W2(S3^{)m{iPWd=@SqE^ z(FajL@4%AI?7Is_y03C zTA?#!K2_^^j2}>cH$MZX^qgqt^PI|lSy@@Jatkegf797j?w&fN0)@ZmITt%p5e>jw z($rqR%;fD8G)4xZD~)~-d#KN5Gfqs82qXEb<4*WHkb!6lY_R?QnDZ~XbCD!Xe`PN0 zgYLMWSNuOT;(D&mqQaYm@P(>(^+Ot>Z~&BIy1M)GqT{o$TCwTqOClArdzMF)q6qoH zYCF}(_x4F^D?b}?vM|5b8AYWLp96#rN9anuW7?G_DtYEe_=qJKMvgw4(e}-W_xYfU z=zF89dw)oC@o`t?g?n}vLX>`Eew8hK-G?oX@xHt|PoOtRSh;UdS-@|MEuw0^7jQLO ziZ|GF1vf~0b)E5}-!Br)vCsEDg#7B5-{2=Fko?)_!ujQ_Rew4VBR~0Vg&~@M;m(GF z&6UQ~5=ii|c+epmKigL818pfkoS$t?p<&H+1jd_zA)!beje5+)Ap#c-LNwp+NB*N1 ztmWi}s*SNWSHflj@7qT0fNqUnd8KSg1&u;>A67IGqNU>4F1jiVXld}$hlZG`lNY6) zoJT#M3Y~0U`(#{{RK`ZiMZo)X2inXC$PW|I@J!P*%cQ)fZCdggj@G|?-4DbvcFnb# ze{;v^xNTlnI&$;B&&4fmd10!v4+pK>KLanRk4r;;fE(G^!3~#t9e3ASvL3(KI4W2d zeOhg817T?AO;n~&W38b74DVmp;h<(QDPJ7A`vyFPm^KxM!?HqpS^MfUW|nCp^RK^o z&y>sz@3xVpZiDK@x+CuFv{)7H=SA&BxjcEAOI_&Cjub+3GWJO3fr1)cl!8Ifn4CXF zkLdBEQ%5(g&vr4}uPB9Y;-vDe*3RZb>WTvIdS83F))t=XF@ID2QVa%wQW=x`TuUeC zodJCm{?dgt`|w5)jaSG$g{Ar1L{mz^1U)F_Zd#gIXi#aR-m@u*K#{dlLVRVEV*+JM z^va)OcW$?&!{6!RE7J-z#(6d0?A4|r=UVA;duLn`Z59Q+W6pQn*fA?gaLMW z*AGJX;sD^Z;$L5M;gxyjjdw@xd&o>vIYOIQ`lpQOE#18mv4EJIkE|^~~QQ1n_H7mlKM%qZjFP|jb;Ou+f5alKT z1ZsbjT46XqIAs^1pXe=x*}+BdR+(pb=5V@cx9aukL7-0mS_#DrGU-wC&KLV*oR7CU z`SGl#Yt->t2tH+3a=$ibDcVGnq74KF;!cYFv{64UT8P2~<}?lX}wNuL899$NX)jL=c7hk{Khs z@!7&0u1C_pS<~N5H^gNXeSMBCW$;kV#GWP7ff~cTD6aN-Pnaw7{^vBUP}&TMu>t8m zdan?hdLdaO%UySwMl9QLk9@B6)WOE`MU*|5X5&pvW9&pDDR@xTLm<&LbiHe7?BF{L zopzc%c{7~@G3IlCe(<-qq?w?LRHB=U&?SGjG4S3^qQkeW^<~WoXD;7!S9i|lg8PZH zul!5sN4;Vnr(~R4W1Yg(9G8VY3rNHOt>$a(xY#urS5+SG(yY>9j{fFq__EK-uRX~= zVln8#lCBXnZ;vllp`YCjK05U$Ef`!&*HwDk0^!#25cqriRfmAgO)DNK|||LCMv? zlvmdhvhP+rK0RZYojlx<=ScR$WdK$2@rN;GE#qSl$sCLp%u+ti>Q2s^F|8$i+M4mP z0S^@NI1C^KHFv#TQ-0@^>~cPEdZBwh=IA%tJlWXx{e%EJ{l^#9pAIUKd*$_V^Yr%5 zM$^cbB>?G3>V;L}uWE+={d0KL2HsT7nrjnw`p)vsT`k@zcif~~!U-8zQ}{A)eCJ2< zy#$De(|AREb%ix_n5yeT$*1Ef_`-rC&hrhib$9_Re>m9R&NP6mZ6DuJM5WZoI}_y{2B z^5!7avV*q3Lr1N*tnKc94>;~D(KoNT8P1OiZJ8^P(h+rVp#mW>kt2J8zVnWts7Q6I z?avn>FjAzWLYEZ546;wdbn$PcSOznQ^gzja8DW$xIDL};XJ(7lmic4xp7XRDE$axh z2wySMGrs0h{x;+~$nO}`87rxFr7KoSK%lqSvb=5HRvf^?^~(A;u>KyWPE-Mw7w8s$ zcPny#8QtJ;Qohe;I|#%DViu*Z@*klko`={%-6K9E^CJy*R_M>q-vXp~C(M8_&6(Xg zS?k61r@a9*n|tgZr{C9Pt~T!lv_l3ML6j8QdLNRvX+MeQ01Bl@;636Jk%HiiB8CXk zwt6GQ0)TO-u$S-3bn>R-dm;o40^S{>x>9OcrJ=LsuSm61RgfmEfzuAHKba!%AM&{Xg3l}rViD|o|3hLzd+!fT1HbG z?=-^1*s@KBnog~@@d7XMox_)Mv4&1zTc7na58&|XAttNGN(=;|1^?=AO3G`KUMO%_ ztqv4s=A&U=g6_A$Yhcikhi%;xLv)Up8Lpdlf!WJbg0K)H?&tC!rK8%nN@lVtvX(}D@9w1f zA6Hao9aYG_uR2irns;43ySE1UzPf$K51^QN(cHp+bn&wKSH5mKjPXgJwdv}z3Ih^h z@N^MiSNN;xKqFbh`UsbJ8)+PD+tCKrV&%^y9aIN&oLj{}?7}L3=;?zZllTE=+sjyU&Sqd|Ov5>0{Z9``d?P#2(6Pg80 zArg%E2N2N<*-8WrD6(g>denwcJ53=#RrshcFN7qfvkht%K~#9M*Z^y z!Y{{!sDlJJ^G@FNh-P+GY4(~OPX6xqSVOBp=9@Nl&;~?67T}0Ali2@)Yu=WBhz!m^ zklR3lu~-k0G?)_IQ7-F@H2j{=2n5c&7z{G(y-XBcxC2(+%gV_fqAYk zvu~FINv!;zB$ksO5vT7dLi23|pi>UH@o5%@CsJ2K*CzU=B3Oro%TFtH$blDmrGIfu z#-r}PQ+5D`+sx?ot}-R3CS^r>^G&9xR)rrJp@GQ^R1VfsTiL6-*tmsmaFqzm)U^jF znE-6{cY;|1ln7`#JNL``IBVG2O8aGpx0lsQy@ ze+%@yYEW8|T6!NA19bnO7!NtrM=#8K4hZzroM-V>l@;F;hjW8a%iM9|tG+faOk4-> z-s3}0bhspt=cC5eoHx*=>qG-*h$tB{-25>8%F&^HLHEQp^+?kV^?RmHl znQTFsuc+4C12rLI)2bm*`a;1;QfTBz=I4??6X3ai4K9@+oIumjw!6hBxW||8)w(7V zTK5FV{2&_UIeC<*NT6yyZBvsx$5}uyCiUV4sSoZ!=jYwZMi=VmF5vw)XBoa=1)%+P zjn-r19@8+0Jm6E*gIcz??Gd{F4fAl;McghnZ%Uvjpvz4T4&(rCqBa!@>EM1LAU@4QZSTl)AvFZS1hn5l&a4rBv4*GT6 zI^`u$B6Cd|{YDP+wxA=ar}}llcbr>5y6XDNd;xju$_i)p{1s4tGt9G&)~z>% zRl@^=o-wHha%9XdO>|2?42|NWZ2c^76}aupquP4GGxaP+K_CPeZ=@x(LT`pMrS;nd z`i)sL5Z%G3ux6!O@EPgq1}k^jn$vaA-(3(#?xpN9&K4&Gp+qZ5PC^FwWipP#q#@*Y zs0!PtvAXa639J_T+4K}vL<&=q*-maWse*vSu`i`!erOK-h;$eap|1C`e=b<0vL8;@ zOAuw?ju?UA0(l;$X-vvX)ZF5tqj{(ZLZLF^Fzn)01$YqzP;jA5%_6VUiu+WXkubn~0%S{BIFE%wC~Y|D^m-Q@>`fUfg$CFM~E zLWX#xX6V(ne>;`EGue-EC=jdfOatNy%e^_ro>0n&k@ia8w@@s0ukwZHyb7QbPg@W!Kqqa(>&4%Hz=LTB-sr(t1zl+MnT}cs{RR6nW zj<~&&0{K#R9I=|`APUSps+mgHT|TT*>MI;`kQg=NfM@-;8RF0k1X0&Pr{h3iAPKCd zsW>@&5J*wPldK5nM?WxS^xP%bY%erxHUKLh_0_BqOz85%ctJcZ=CSv&3Bj;Cf2lv+ zwf$E5gBVB%GOUR(AA`j>7uDB|oY)m^)BYfmxw)e)aD6cm5~$s}fiVF5v*+Jqi{|lZ zTf2*Bie)D-_<B-RAx?luCc8S>2oRHDmMrXCSHjgNVkGw-!TNI|h)2SKC*z(pE-(TkB04 z!$Bqo5kQrR<76YZq=y9p)|{NwMnYB@2B!iv%Vy)dS`~~^=@ogU>&xZ> zQ*3%*(HXQ|MC?c7_MrjRRW&?ZSM$Y=g?=}kwul1{E-e|!)4k~qmj}>Y4px6Z=?-dH zi1`ZAt4edXR;7THxX+^!LNymS?)@Dof}BQOZ@0tUJ%`HD@r15$liwQz0CV>>-&E9{ zlZD}hGNR~%(Rfaw-`-;gSQ&lrxZabq{%0N4f7WZ1;JsF&h4}Unuk^^%D1l{hWa$I~ zPx;6$nZk6Gqz*vD%<}`=J@ocZ1vFJ_0^BY3ZzN;{$3BO*L3;gYX3-~Kh#q!zH#+7@ zsD>T7VJNd323%!L=3mAoJ7>D>)Dqn7A%j9P`F+E)D(|)xPrN6w^glWzRdaT&{dN=! z_bs8IwsD1DaD(OVwMWd$3M}v)5yY(@(KY`Df5R8BgG90$1srd7&oVh8gBS{L<>eor zH=X!R_7Yj41`V79?Kzx|ILhrqEq%n-U%sVyt*y!P3Z%<5&9{c)P?C8GXtvGuK|VSy z8St%1_3usZ+B=x$01Z*A3u)*4z+mb&X14pXY|keOSQ!<{Mb7!X5C%yi4xof=j+W81 zp~S+|aNwqs$}%H>=n4tE`*He=d%o&8lSIf+AQ z_nOwPG`1N}t3fWDf1$JSqT2gbU$a}j<`6jm%Jgkc5~%^q)sefKb6_+^+xk`B$$J%1 z5;vvA6mdnALDgtZOe2(jG!Zfg)N{D=mskdxwm~iSzF+j;{R==}m7Aijxqc(<(iV@- zT@;FQDx|q4>#z7GntYhLamxwVPO(7^1DLQeq+B5=x%l0aTG)dyda;~Tp^812baq&J zeu?bemY|A=16gm|@EIpRW8-i_U5vR)`2IISz>jozj+H)vDwTLY0gF*`NFGr4V3gp= zmji@8X}8Sumn!*0p5t1?z|Rn5wR&!++`#nvCp{rR5uMNieb>$78ZMK1?qk_T^)a+} zTpQF@ZMrUP7Q*s%*aB^~iS3}Rh*Q)BrfK?_U7%99Lj^6PZQRoy@9^ST>hlVkzet*E zTT8Czysn8ri5*nGLz!t)O{c0U+HEt6a#$vcQ$uj~wm6yqs{E1T0pTZi(bg3+7c?HI z{Z@lTWpgj$*5$E&cw+-Wn1cRRum)_q42(z6TZq#&wjDqg`{hP7%7Zw<+8Zki(>oB) z=1n^LT&EX>zCB-s_TWX}lHw@{+~hJ2l*X@?DauzV!w5cP*oJn#-=1`Z0Gs5K<^4C$ zi9Vp2lUg`@UeSJaM92n7!P3pA-6PX0gQDaW0TY(1(aG3EO5o@YJkDfTNj~P82^t(s zWLE-)Z6L+*1LDZrF*7a4E#{wM&Cd^amIHzNPFbS(;*?$zU}EH;5gN+KdKk^<>=JE+5F=f<8ImnC{|L_cS+ZQ77oGSVk~iXLXtIvS_f4jV zcTB2z)i~%Mj4O7A_7oAFjR_+k_TUV@&Qg(ZE44cQ$;Jiz7%YtrV(U-xIe_d-z(ONR z(U?dFEpS%&HF>|TPfqnA`|LBJ_2Zk5BLm3T)r8@jTL_vbF}1_QL$9+CTYc7-zYj&A zU%h5}_wV(O`D{Q%G>&4D*#@c!lL3a7zqtOsT6_6nc6W{d0&q(8x?Gb_m1M#ZHw>zW z|AGs2xyk%oQ29sU1jbMsYE^VT73i$FqW+}?uo)=jGVS4G22?vak~%pH;$z!yt)f}9CZM)}YIYFw2g zts;&^Cf;0#%&+1*bJ*F0BF;jB1+0H$pM&u3vgKrV|JBii(B%LoT*w358_ zeHjT?@*5p+b>IFh&n;EQomII+2j32eVkbq1;7RtN^#Fw={iP8I&pp2W-6vtF)Gg5t zcayLyC|M)e$HlQ~hJZQ%TtEO<{pms~9AIc!Eocukj%;>+AO4FY`HfYjqFo^UknrhS z)ByJnz_IWAs?rQC{KN{Vm^$yjCrwn6^5yGfE|{8?8o<^#(|QSABgFl$8Eb$p1}DG+ z;-wQfOcI@d=>l0hfHolaNwOod<_-Q++XlDD41O9%vNe?v0&cPeui%{tIR^&V*8<*_ zU8NLMv!Q^^6><9z5cQsJyyYW30HBbT4i!to$qfRx5Bc2xb^dq0JUb1=5e8KNPBufl zR@OSRD%EHOk|hmdWiERBzc&NCApa;m@_ytuq^8d013k>x0uz(xwjTOgZXvPvZyq{M zi1%NsmwcXDJ*J43-T@S6Tn`x}*qOk4qb4cmepLk87YRUx4lc&E$3l%4z^p~CaBPQd zMEKux+)@7T78qWDy;WFkz40|14o+GLB<0!ZYxkx5s{p@SCa{$7bQK&)DA!XTg-DzP zDXZZ{PgIc!j@fK!;8VX$2D^x1A(?-b3gx9$ZzCQBn1seHjh4)Aoddq43K>w~ORv2R zk@+onNQn6kXYrZ@EIuPGejIqpwJ>Y2!wlV{@0u&mQ-|%md0LEKp~(Gr!T)(klrq{r zX#X|#e_H(ezZU;b_u@#(Q_8}L|4;k=`}z&XQzQT1)5n7U8z=wgbCf8c=KjyA;Gbt7 z2p}*2@8?|X90=9_y%e?Q3na+@UiyC@`2UxN+2b;lyaxjQp8czD?bdk_i6;K^=>@*e z(}9B?0tXJpN)UK(XitP7f`bny94a_KOyF^z4qb>;Plt&AJ@J1Z4j2dje;GNIkk($r VgK8%Km8a4DMn*-tOw!oz{{hjLYpehO diff --git a/docs/assets/quantflow-repo.svg b/docs/assets/quantflow-repo.svg deleted file mode 100644 index 99084c69..00000000 --- a/docs/assets/quantflow-repo.svg +++ /dev/null @@ -1,203 +0,0 @@ - - - - - - - - - - - - Quantflow - - - - - - - - - - A modern python library for quantitative finance - - - - - - - - - - Qf - - - - - - - - - diff --git a/docs/assets/quantflow.svg b/docs/assets/quantflow.svg deleted file mode 100644 index 831faee7..00000000 --- a/docs/assets/quantflow.svg +++ /dev/null @@ -1,252 +0,0 @@ - - - - - - - - - - - - - Quantflow - - - - - - - - - - - - - - - - - Quantflow - - - - - - - - - - A modern python library for quantitative finance - - - - diff --git a/docs/examples/vol_surface_bns2_calibration.py b/docs/examples/vol_surface_bns2_calibration.py index f051f98e..7739d214 100644 --- a/docs/examples/vol_surface_bns2_calibration.py +++ b/docs/examples/vol_surface_bns2_calibration.py @@ -14,12 +14,15 @@ surface.disable_outliers() # Two-factor BNS: a fast factor for short maturities and a slow one for long. -# Opposite-sign leverages lets one factor lift the OTM-call wing (rho>0) while -# the other carries the equity-style downside skew (rho<0). +# Both factors share the same Gamma stationary marginal (vol, decay) following +# the BNS superposition-of-OU construction; only the timescale (kappa) and +# leverage (rho) differ. Opposite-sign leverages lets one factor lift the +# OTM-call wing (rho>0) while the other carries the equity-style downside +# skew (rho<0). pricer = OptionPricer( model=BNS2( - bns1=BNS.create(vol=0.4, kappa=20.0, decay=20.0, rho=-0.6), - bns2=BNS.create(vol=0.5, kappa=0.3, decay=5.0, rho=0.3), + bns1=BNS.create(vol=0.45, kappa=20.0, decay=10.0, rho=-0.6), + bns2=BNS.create(vol=0.45, kappa=0.3, decay=10.0, rho=0.3), weight=0.3, ) ) @@ -27,7 +30,7 @@ calibration: BNS2Calibration[BNS2] = BNS2Calibration( pricer=pricer, vol_surface=surface, - moneyness_weight=0.5, + moneyness_weight=0.2, ) result = calibration.fit() diff --git a/docs/index.md b/docs/index.md index 3abcf349..700c521b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -34,7 +34,7 @@ pip install quantflow ## MCP Server Quantflow exposes its data tools as an [MCP](https://modelcontextprotocol.io) server for AI clients. -See [MCP Server](https://quanflow.quantmind.com/mcp) for setup and available tools. +See [MCP Server](https://quantflow.quantmind.com/mcp/) for setup and available tools. ## License diff --git a/docs/tutorials/bns_calibration.md b/docs/tutorials/bns_calibration.md index 55be5ddc..e9ab00bd 100644 --- a/docs/tutorials/bns_calibration.md +++ b/docs/tutorials/bns_calibration.md @@ -25,9 +25,11 @@ parameters to the surface: The BDLP intensity is set as $\lambda = \theta \beta$ so that the stationary mean of the Gamma-OU variance process equals $\theta$. This gives the same -$(v_0, \theta)$ parameterisation as Heston. Because the variance is built from -positive jumps and exponential mean reversion, it stays positive by -construction; no Feller-style penalty is needed. +$(v_0, \theta)$ parameterisation as Heston. + +Because the variance is built from positive jumps and exponential mean +reversion, it stays positive by construction. No Feller-style penalty is +needed. ### How BNS fits the surface @@ -43,10 +45,12 @@ A consequence of this structural difference is that the calibrator often settles at a small $\kappa$ together with a large $\theta$. The time scale of mean reversion is $1/\kappa$, so when $\kappa$ is small the variance process barely relaxes towards $\theta$ over the calibration horizon and stays close -to $v_0$ throughout. In that regime $\theta$ is only weakly identified by the -surface and the optimizer can move it freely as long as the jump-driven smile -dynamics are preserved. The headline number to read in the output is $v_0$, -which sets the at-the-money level. +to $v_0$ throughout. + +In that regime $\theta$ is only weakly identified by the surface and the +optimizer can move it freely as long as the jump-driven smile dynamics are +preserved. The headline number to read in the output is $v_0$, which sets +the at-the-money level. ### Calibrated parameters @@ -96,16 +100,26 @@ short-maturity skew from the long-maturity level, in the same spirit as the [DoubleHeston][quantflow.sp.heston.DoubleHeston] extension of Heston. [BNS2Calibration][quantflow.options.calibration.bns.BNS2Calibration] fits -eleven parameters: +nine parameters: -`[v01, theta1, kappa_delta, beta1, rho1, v02, theta2, kappa2, beta2, rho2, w]` +`[v01, v02, theta, beta, kappa2, kappa_delta, rho1, rho2, w]` with `kappa1 = kappa2 + kappa_delta` enforcing that the first factor -mean-reverts faster than the second. Both leverage parameters are free in -$[-0.9, 0.9]$: a positive $\rho_i$ produces up-jumps in the log-price that -lift the OTM call wing, while a negative one produces equity-style downside -skew. There is no warm start, so the optimiser starts from the user-supplied -initial parameters; pick distinct timescales for `bns1` and `bns2` (and +mean-reverts faster than the second. + +Following the BNS superposition-of-OU construction, both factors share the +same Gamma stationary marginal: the intensity and decay of the BDLP are tied +across factors so that $v^1$ and $v^2$ have the same long-run distribution. +Only the timescales and the leverages differ between the two factors. + +Tying $(\theta, \beta)$ removes a well-known degeneracy between the +marginal-distribution parameters and the timescales, and shrinks the search +space without losing skew flexibility. The leverages $\rho_1, \rho_2$ stay +independent because the empirical equity skew flattens with maturity, which a +single shared leverage cannot reproduce. + +There is no warm start, so the optimiser begins from the user-supplied +initial parameters. Pick distinct timescales for `bns1` and `bns2` (and consider opposite-sign leverages) to seed a meaningful two-factor fit. ### Calibrated parameters @@ -115,10 +129,12 @@ consider opposite-sign leverages) to seed a meaningful two-factor fit. [![BNS2 calibrated smile](../assets/examples/bns2_calibrated_smile.png)](../assets/examples/bns2_calibrated_smile.png){target="_blank"} The two-factor variant adds flexibility on the term structure: the fast factor -absorbs short-dated skew while the slow factor anchors the long end. The -remaining short-maturity gap is structural in the same way as the single-factor -case: BNS2 still injects jumps only through the variance process, so the -log-price wings are bounded by the jump sizes scaled by $|\rho_i|$. +absorbs short-dated skew while the slow factor anchors the long end. + +The remaining short-maturity gap is structural in the same way as the +single-factor case. BNS2 still injects jumps only through the variance +process, so the log-price wings are bounded by the jump sizes scaled by +$|\rho_i|$. ### Code diff --git a/docs/tutorials/volatility_surface.md b/docs/tutorials/volatility_surface.md index 9a5682e3..31ef8024 100644 --- a/docs/tutorials/volatility_surface.md +++ b/docs/tutorials/volatility_surface.md @@ -110,10 +110,18 @@ volatility surface using a two-stage optimisation: solution on the residual vector with tight tolerances and enforces parameter bounds. Residuals are computed as `weight * (model_call_price - mid_call_price)` where -`mid_call_price` is the average of the bid and ask call prices, and the weight is -$e^{-w \cdot |k|}$ controlled by `moneyness_weight`. A penalty for violating the -Feller condition ($2\kappa\theta \geq \sigma^2$) is added during stage 1 to keep the -variance process well-behaved. +`mid_call_price` is the average of the bid and ask call prices. + +The weight is $\min(e^{w \cdot m^2}, w_\text{max})$ controlled by +`moneyness_weight` (the coefficient $w$) and `max_cost_weight` (the cap +$w_\text{max}$), with $m = \log(K/F)/\sqrt{T}$ the standardised moneyness. +The quadratic exponent matches the gaussian shape of $1/\nu$ (inverse vega), +so a positive `moneyness_weight` puts wing residuals on the same footing as +ATM ones. The cap prevents a single deep-wing option from dominating the +loss. + +A penalty for violating the Feller condition ($2\kappa\theta \geq \sigma^2$) +is added during stage 1 to keep the variance process well-behaved. ```python --8<-- "docs/examples/vol_surface_heston_calibration.py" @@ -125,9 +133,10 @@ variance process well-behaved. ### Calibration Options -The `moneyness_weight` parameter down-weights far-from-the-money options via -$e^{-w \cdot |k|}$ where $k = \log(K/F)$. Setting `ttm_weight > 0` similarly -down-weights near-expiry options. +The `moneyness_weight` parameter up-weights far-from-the-money options via +$e^{w \cdot m^2}$ where $m = \log(K/F)/\sqrt{T}$ is the standardised +moneyness. The result is capped at `max_cost_weight` (default 10) so a +single deep-wing option cannot dominate the loss. ### Plotting the Calibrated Smile diff --git a/quantflow/options/calibration/base.py b/quantflow/options/calibration/base.py index 541296c5..0ca3dd01 100644 --- a/quantflow/options/calibration/base.py +++ b/quantflow/options/calibration/base.py @@ -85,9 +85,22 @@ class VolModelCalibration(BaseModel, ABC, Generic[M]): default=0.0, ge=0.0, description=( - "Weight penalising options as moneyness moves away from 0." - " Applied as `exp(-moneyness_weight * |moneyness|)`." - " A value of 0 applies no penalisation." + "Coefficient that up-weights wing options in the cost function." + " Applied as `min(exp(moneyness_weight * moneyness**2)," + " max_cost_weight)`, with `moneyness = log(K/F) / sqrt(ttm)`." + " The quadratic form mimics the gaussian shape of `1/vega` and" + " puts wing residuals on the same footing as ATM ones. A value" + " of 0 applies no moneyness weighting; typical values are in" + " `[0.1, 0.5]`." + ), + ) + max_cost_weight: float = Field( + default=10.0, + gt=0.0, + description=( + "Hard cap on the per-option cost weight, to prevent a single" + " deep-wing option from dominating the loss when" + " `moneyness_weight` is large." ), ) options: dict[ModelCalibrationEntryKey, OptionEntry] = Field( @@ -170,9 +183,14 @@ def fit(self) -> OptimizeResult: return result def cost_weight(self, ttm: float, log_strike: float) -> float: - """Weight for a given time to maturity and log-strike""" + """Weight for a given time to maturity and log-strike. + + Up-weights wing options via `exp(moneyness_weight * moneyness**2)`, + capped at `max_cost_weight`. The quadratic form mimics `1/vega`. + """ moneyness = log_strike / np.sqrt(ttm) - return np.exp(-self.moneyness_weight * abs(moneyness)) + weight = np.exp(self.moneyness_weight * moneyness * moneyness) + return float(min(weight, self.max_cost_weight)) def penalize(self) -> float: """Additional scalar penalty added to the cost function (default: 0)""" diff --git a/quantflow/options/calibration/bns.py b/quantflow/options/calibration/bns.py index 99771d9e..36e3bebd 100644 --- a/quantflow/options/calibration/bns.py +++ b/quantflow/options/calibration/bns.py @@ -61,31 +61,35 @@ def set_params(self, params: np.ndarray) -> None: class BNS2Calibration(VolModelCalibration[B2], Generic[B2]): r"""Calibration of the [BNS2][quantflow.sp.bns.BNS2] two-factor BNS model. - The parameter vector is - - `[v01, theta1, kappa_delta, beta1, rho1, v02, theta2, kappa2, beta2, rho2, w]` - - where `kappa1 = kappa2 + kappa_delta` with `kappa_delta > 0`, enforcing that - the first (short-maturity) factor mean-reverts faster than the second, and - `w` is the convex-combination weight of the first variance factor. The same - $(v_0, \theta)$ parameterisation as - [BNSCalibration][quantflow.options.calibration.bns.BNSCalibration] is used - for each factor: the BDLP intensity is set as $\lambda_i = \theta_i \beta_i$ - so the stationary mean of $v^i$ equals $\theta_i$. - - Both leverage parameters are free in $[-0.9, 0.9]$: a positive $\rho_i$ - produces up-jumps in the log-price that lift the OTM call wing, while a - negative one produces equity-style downside skew. The joint fit relies on - the user-supplied initial parameters: pick distinct timescales for `bns1` - and `bns2` (and consider opposite-sign leverages) to give the optimiser a - meaningful two-factor starting point. - - TODO: improve this calibration. The 11-parameter fit is slow (finite-diff - Jacobian dominates) and tends to collapse the two timescales into a near - single-factor solution unless the initial conditions force them apart. - Candidate improvements: analytic Jacobian of the characteristic exponent, - a smarter warm start that does not bias the kappas to merge, and tighter - bounds on `kappa1` and `beta_i`. + Following the BNS superposition-of-OU construction, both factors share + the same Gamma stationary marginal: only the mean-reversion timescales + and the leverage parameters differ between the fast and slow factors. + The parameter vector has nine entries: + + `[v01, v02, theta, beta, kappa2, kappa_delta, rho1, rho2, w]` + + | Symbol | Description | + |---|---| + | `v01`, `v02` | Initial variances of the two factors | + | `theta` | Long-run variance shared by both factors ($\theta = \lambda / \beta$) | + | `beta` | Exponential decay of the BDLP jump-size distribution (shared) | + | `kappa2` | Mean-reversion speed of the slow factor | + | `kappa_delta` | Excess speed of the fast factor ($\kappa_1 - \kappa_2$) | + | `rho1`, `rho2` | Leverage of the two factors, free in $[-0.9, 0.9]$ | + | `w` | Weight of the first variance factor in the convex combination | + + Tying $(\theta, \beta)$ removes the degeneracy between the two + marginal-distribution parameters and the timescales: the long-dated smile + pins down a single stationary variance distribution, while the term + structure of vol identifies the two relaxation speeds. The leverages + $\rho_1, \rho_2$ stay independent because the empirical equity skew + flattens with maturity, which a single shared leverage cannot reproduce. + + The user-supplied initial model still seeds the fit: pick distinct + timescales for `bns1` and `bns2` (and consider opposite-sign leverages) so + the optimiser starts away from the single-factor collapse. Any difference + in `(theta, beta)` between the two seed factors is averaged when building + the starting parameter vector. """ def get_bounds(self) -> Bounds: @@ -95,43 +99,46 @@ def get_bounds(self) -> Bounds: v2 = vol_lb**2 v2u = vol_ub**2 return Bounds( - [v2, v2, 1e-4, 1.0, -0.9, v2, v2, 1e-3, 1.0, -0.9, 0.0], - [v2u, v2u, np.inf, np.inf, 0.9, v2u, v2u, 5.0, np.inf, 0.9, 1.0], + # v01, v02, theta, beta, kappa2, kappa_delta, rho1, rho2, w + [v2, v2, v2, 1.0, 1e-3, 1e-4, -0.9, -0.9, 0.0], + [v2u, v2u, v2u, np.inf, 5.0, np.inf, 0.9, 0.9, 1.0], ) def get_params(self) -> np.ndarray: vp1 = self.model.bns1.variance_process vp2 = self.model.bns2.variance_process - kappa_delta = max(vp1.kappa - vp2.kappa, 1e-4) theta1 = vp1.intensity / vp1.beta theta2 = vp2.intensity / vp2.beta + theta = 0.5 * (theta1 + theta2) + beta = 0.5 * (vp1.beta + vp2.beta) + kappa_delta = max(vp1.kappa - vp2.kappa, 1e-4) return np.asarray( [ vp1.rate, - theta1, - kappa_delta, - vp1.beta, - self.model.bns1.rho, vp2.rate, - theta2, + theta, + beta, vp2.kappa, - vp2.beta, + kappa_delta, + self.model.bns1.rho, self.model.bns2.rho, self.model.weight, ] ) def set_params(self, params: np.ndarray) -> None: + v01, v02, theta, beta, kappa2, kappa_delta, rho1, rho2, w = params vp1 = self.model.bns1.variance_process - vp1.rate = params[0] - vp1.bdlp.jumps.decay = params[3] - vp1.bdlp.intensity = params[1] * params[3] - self.model.bns1.rho = params[4] vp2 = self.model.bns2.variance_process - vp2.rate = params[5] - vp2.kappa = params[7] - vp2.bdlp.jumps.decay = params[8] - vp2.bdlp.intensity = params[6] * params[8] - self.model.bns2.rho = params[9] - vp1.kappa = vp2.kappa + params[2] # kappa2 + kappa_delta - self.model.weight = params[10] + vp1.rate = v01 + vp2.rate = v02 + vp1.bdlp.jumps.decay = beta + vp2.bdlp.jumps.decay = beta + intensity = theta * beta + vp1.bdlp.intensity = intensity + vp2.bdlp.intensity = intensity + vp2.kappa = kappa2 + vp1.kappa = kappa2 + kappa_delta + self.model.bns1.rho = rho1 + self.model.bns2.rho = rho2 + self.model.weight = w diff --git a/readme.md b/readme.md index adc14415..700c521b 100644 --- a/readme.md +++ b/readme.md @@ -1,4 +1,4 @@ -# +# [![PyPI version](https://badge.fury.io/py/quantflow.svg)](https://badge.fury.io/py/quantflow) [![Python versions](https://img.shields.io/pypi/pyversions/quantflow.svg)](https://pypi.org/project/quantflow) @@ -33,7 +33,8 @@ pip install quantflow ## MCP Server -Quantflow exposes its data tools as an [MCP](https://modelcontextprotocol.io) server for AI clients. See [MCP Server](mcp.md) for setup and available tools. +Quantflow exposes its data tools as an [MCP](https://modelcontextprotocol.io) server for AI clients. +See [MCP Server](https://quantflow.quantmind.com/mcp/) for setup and available tools. ## License