From aa94a44180556af6265671e9b84df9508733ce09 Mon Sep 17 00:00:00 2001 From: Stephen Farr Date: Thu, 18 May 2023 18:32:22 +0100 Subject: [PATCH] add umbrella sampling tutorial (#24) * add umbrella sampling tutorial * Improve explanation, theory, references, and figures * fix typos * code formatting and text fixes * links in markdown * minor changes * minor changes --- notebooks/tutorials/deca-ala.pdb | 111 + notebooks/tutorials/deca-alanine.png | Bin 0 -> 78160 bytes notebooks/tutorials/hist.png | Bin 0 -> 11038 bytes notebooks/tutorials/pmf.png | Bin 0 -> 20552 bytes notebooks/tutorials/umbrella_sampling.ipynb | 445 ++++ notebooks/tutorials/umbrella_sampling.svg | 2305 +++++++++++++++++++ tutorials.md | 1 + 7 files changed, 2862 insertions(+) create mode 100644 notebooks/tutorials/deca-ala.pdb create mode 100755 notebooks/tutorials/deca-alanine.png create mode 100644 notebooks/tutorials/hist.png create mode 100644 notebooks/tutorials/pmf.png create mode 100644 notebooks/tutorials/umbrella_sampling.ipynb create mode 100644 notebooks/tutorials/umbrella_sampling.svg diff --git a/notebooks/tutorials/deca-ala.pdb b/notebooks/tutorials/deca-ala.pdb new file mode 100644 index 0000000..8411a6d --- /dev/null +++ b/notebooks/tutorials/deca-ala.pdb @@ -0,0 +1,111 @@ +TITLE DECA-ALA +ATOM 1 1HH3 ACE 1 6.138 4.146 -3.223 1.00 0.00 +ATOM 2 CH3 ACE 1 6.844 3.333 -3.064 1.00 0.00 +ATOM 3 2HH3 ACE 1 7.542 3.605 -2.273 1.00 0.00 +ATOM 4 3HH3 ACE 1 7.394 3.142 -3.984 1.00 0.00 +ATOM 5 C ACE 1 6.095 2.085 -2.664 1.00 0.00 +ATOM 6 O ACE 1 4.870 2.104 -2.562 1.00 0.00 +ATOM 7 N ALA 2 6.826 0.999 -2.415 1.00 0.00 +ATOM 8 H ALA 2 7.827 1.065 -2.529 1.00 0.00 +ATOM 9 CA ALA 2 6.255 -0.311 -2.082 1.00 0.00 +ATOM 10 HA ALA 2 5.611 -0.625 -2.905 1.00 0.00 +ATOM 11 CB ALA 2 7.405 -1.320 -1.966 1.00 0.00 +ATOM 12 HB1 ALA 2 8.078 -1.036 -1.155 1.00 0.00 +ATOM 13 HB2 ALA 2 7.001 -2.312 -1.760 1.00 0.00 +ATOM 14 HB3 ALA 2 7.964 -1.357 -2.902 1.00 0.00 +ATOM 15 C ALA 2 5.391 -0.293 -0.803 1.00 0.00 +ATOM 16 O ALA 2 4.342 -0.937 -0.761 1.00 0.00 +ATOM 17 N ALA 3 5.779 0.486 0.214 1.00 0.00 +ATOM 18 H ALA 3 6.661 0.970 0.133 1.00 0.00 +ATOM 19 CA ALA 3 4.999 0.663 1.443 1.00 0.00 +ATOM 20 HA ALA 3 4.769 -0.321 1.857 1.00 0.00 +ATOM 21 CB ALA 3 5.863 1.418 2.462 1.00 0.00 +ATOM 22 HB1 ALA 3 6.121 2.408 2.082 1.00 0.00 +ATOM 23 HB2 ALA 3 5.312 1.529 3.396 1.00 0.00 +ATOM 24 HB3 ALA 3 6.778 0.857 2.660 1.00 0.00 +ATOM 25 C ALA 3 3.657 1.385 1.193 1.00 0.00 +ATOM 26 O ALA 3 2.625 0.977 1.730 1.00 0.00 +ATOM 27 N ALA 4 3.645 2.413 0.336 1.00 0.00 +ATOM 28 H ALA 4 4.515 2.694 -0.091 1.00 0.00 +ATOM 29 CA ALA 4 2.424 3.116 -0.068 1.00 0.00 +ATOM 30 HA ALA 4 1.867 3.391 0.829 1.00 0.00 +ATOM 31 CB ALA 4 2.815 4.408 -0.797 1.00 0.00 +ATOM 32 HB1 ALA 4 3.367 4.180 -1.709 1.00 0.00 +ATOM 33 HB2 ALA 4 1.913 4.964 -1.060 1.00 0.00 +ATOM 34 HB3 ALA 4 3.432 5.030 -0.147 1.00 0.00 +ATOM 35 C ALA 4 1.505 2.227 -0.929 1.00 0.00 +ATOM 36 O ALA 4 0.290 2.220 -0.726 1.00 0.00 +ATOM 37 N ALA 5 2.073 1.420 -1.834 1.00 0.00 +ATOM 38 H ALA 5 3.070 1.509 -1.999 1.00 0.00 +ATOM 39 CA ALA 5 1.328 0.431 -2.617 1.00 0.00 +ATOM 40 HA ALA 5 0.514 0.940 -3.136 1.00 0.00 +ATOM 41 CB ALA 5 2.268 -0.162 -3.674 1.00 0.00 +ATOM 42 HB1 ALA 5 3.094 -0.689 -3.195 1.00 0.00 +ATOM 43 HB2 ALA 5 1.716 -0.864 -4.301 1.00 0.00 +ATOM 44 HB3 ALA 5 2.667 0.633 -4.305 1.00 0.00 +ATOM 45 C ALA 5 0.699 -0.663 -1.728 1.00 0.00 +ATOM 46 O ALA 5 -0.472 -1.005 -1.906 1.00 0.00 +ATOM 47 N ALA 6 1.434 -1.164 -0.728 1.00 0.00 +ATOM 48 H ALA 6 2.409 -0.894 -0.661 1.00 0.00 +ATOM 49 CA ALA 6 0.921 -2.119 0.258 1.00 0.00 +ATOM 50 HA ALA 6 0.503 -2.976 -0.273 1.00 0.00 +ATOM 51 CB ALA 6 2.093 -2.615 1.114 1.00 0.00 +ATOM 52 HB1 ALA 6 2.546 -1.785 1.656 1.00 0.00 +ATOM 53 HB2 ALA 6 1.733 -3.354 1.832 1.00 0.00 +ATOM 54 HB3 ALA 6 2.845 -3.082 0.478 1.00 0.00 +ATOM 55 C ALA 6 -0.204 -1.519 1.125 1.00 0.00 +ATOM 56 O ALA 6 -1.225 -2.173 1.343 1.00 0.00 +ATOM 57 N ALA 7 -0.069 -0.260 1.562 1.00 0.00 +ATOM 58 H ALA 7 0.813 0.216 1.405 1.00 0.00 +ATOM 59 CA ALA 7 -1.119 0.457 2.290 1.00 0.00 +ATOM 60 HA ALA 7 -1.408 -0.138 3.158 1.00 0.00 +ATOM 61 CB ALA 7 -0.542 1.785 2.798 1.00 0.00 +ATOM 62 HB1 ALA 7 -0.238 2.413 1.959 1.00 0.00 +ATOM 63 HB2 ALA 7 -1.299 2.313 3.380 1.00 0.00 +ATOM 64 HB3 ALA 7 0.322 1.595 3.436 1.00 0.00 +ATOM 65 C ALA 7 -2.385 0.673 1.434 1.00 0.00 +ATOM 66 O ALA 7 -3.498 0.442 1.911 1.00 0.00 +ATOM 67 N ALA 8 -2.230 1.043 0.157 1.00 0.00 +ATOM 68 H ALA 8 -1.296 1.266 -0.171 1.00 0.00 +ATOM 69 CA ALA 8 -3.340 1.187 -0.789 1.00 0.00 +ATOM 70 HA ALA 8 -4.075 1.870 -0.359 1.00 0.00 +ATOM 71 CB ALA 8 -2.799 1.819 -2.078 1.00 0.00 +ATOM 72 HB1 ALA 8 -2.056 1.166 -2.537 1.00 0.00 +ATOM 73 HB2 ALA 8 -3.619 1.973 -2.781 1.00 0.00 +ATOM 74 HB3 ALA 8 -2.342 2.784 -1.855 1.00 0.00 +ATOM 75 C ALA 8 -4.057 -0.150 -1.069 1.00 0.00 +ATOM 76 O ALA 8 -5.287 -0.181 -1.152 1.00 0.00 +ATOM 77 N ALA 9 -3.315 -1.261 -1.156 1.00 0.00 +ATOM 78 H ALA 9 -2.305 -1.167 -1.154 1.00 0.00 +ATOM 79 CA ALA 9 -3.880 -2.606 -1.280 1.00 0.00 +ATOM 80 HA ALA 9 -4.598 -2.610 -2.102 1.00 0.00 +ATOM 81 CB ALA 9 -2.748 -3.580 -1.635 1.00 0.00 +ATOM 82 HB1 ALA 9 -2.006 -3.608 -0.837 1.00 0.00 +ATOM 83 HB2 ALA 9 -3.158 -4.581 -1.774 1.00 0.00 +ATOM 84 HB3 ALA 9 -2.267 -3.265 -2.562 1.00 0.00 +ATOM 85 C ALA 9 -4.633 -3.046 -0.006 1.00 0.00 +ATOM 86 O ALA 9 -5.740 -3.582 -0.098 1.00 0.00 +ATOM 87 N ALA 10 -4.078 -2.775 1.182 1.00 0.00 +ATOM 88 H ALA 10 -3.146 -2.376 1.198 1.00 0.00 +ATOM 89 CA ALA 10 -4.714 -3.071 2.471 1.00 0.00 +ATOM 90 HA ALA 10 -4.996 -4.125 2.486 1.00 0.00 +ATOM 91 CB ALA 10 -3.681 -2.837 3.580 1.00 0.00 +ATOM 92 HB1 ALA 10 -3.374 -1.791 3.596 1.00 0.00 +ATOM 93 HB2 ALA 10 -4.117 -3.094 4.546 1.00 0.00 +ATOM 94 HB3 ALA 10 -2.806 -3.467 3.412 1.00 0.00 +ATOM 95 C ALA 10 -5.996 -2.247 2.716 1.00 0.00 +ATOM 96 O ALA 10 -6.949 -2.749 3.317 1.00 0.00 +ATOM 97 N ALA 11 -6.049 -1.006 2.218 1.00 0.00 +ATOM 98 H ALA 11 -5.204 -0.623 1.810 1.00 0.00 +ATOM 99 CA ALA 11 -7.237 -0.146 2.244 1.00 0.00 +ATOM 100 HA ALA 11 -7.666 -0.182 3.247 1.00 0.00 +ATOM 101 CB ALA 11 -6.777 1.294 1.978 1.00 0.00 +ATOM 102 HB1 ALA 11 -6.348 1.371 0.978 1.00 0.00 +ATOM 103 HB2 ALA 11 -7.628 1.972 2.053 1.00 0.00 +ATOM 104 HB3 ALA 11 -6.029 1.588 2.715 1.00 0.00 +ATOM 105 C ALA 11 -8.353 -0.574 1.259 1.00 0.00 +ATOM 106 O ALA 11 -9.466 -0.049 1.310 1.00 0.00 +ATOM 107 N NH2 12 -8.107 -1.516 0.354 1.00 0.00 +ATOM 108 HN1 NH2 12 -7.197 -1.950 0.308 1.00 0.00 +ATOM 109 HN2 NH2 12 -8.840 -1.786 -0.282 1.00 0.00 +TER diff --git a/notebooks/tutorials/deca-alanine.png b/notebooks/tutorials/deca-alanine.png new file mode 100755 index 0000000000000000000000000000000000000000..792a74f00ee3d84f6e2b88aa7b002cfd5ddf7aff GIT binary patch literal 78160 zcmdSBg4r;kWv8;EfUfkX{Eb6q&p=Aq&uZk8tLwqZjcb9OFE>xJKlZ3=lMO) z`+onxrMHNFd;wB~KwI z-~-lHK~w;ybnx{S@WWRlRq;>K(l9i@H4+R0EG7&b^cLVR3@knj!s9gzj07yfe_t!W zQvJIJ7&E{W2L9hY>cA)Tk38@Xc>3QbTsrK3Mob6&*WK`J>2Uvb4blbfhRIk2rvV?x z)?#Y5FfeHL(0{P+oMM0rJ{WN!enltP-T7y3hQ`kH_qKzlnIrk;Ik7*~O_ORb_CM3@ zXzg~*{{cVv!U~qd2EdR!NTP`+&smd@QRpIh!{6Y)3Ut+)oprUEQ95uB&b>&q^~|a; za&~+t*>CoKjWw;>jm5U_#zV)HWypDfw679!$PbGm=LG_%!yr)c0hh#y@Y#kmX#E2J z*VlAye15#o{`)rQ6MUn{407TP6nfr|PyY8Hh%~o&|25pxmr*ia-V&qlkx_;I*Qg9~ z%R~QO`|sgMI}n;;RH?Ws@&B5Xmp6(h;{SSyclImY^e8*&4v_qRzZd!ln&KrhbQ%Bo zk}L%VE;id76Fcxfiv)hFo8FQ3zwVPG-h#)?C)0{9=lfr)gn`4lNBbY+0hi*GZG7Zg z-@hVc{;%2N<{ujW=e^KJ#5iCPX~d_HpZ;-+kS%b5u}(l5aL$fq>|*Rr4z z_eKMkqw)B(6Ccxj{`~pw?ykAH8E>%=tJdSpkdyxOSGCfgxRy zhWpJ+{a8O#912r4H3)Rnzi-?4jNCMxm7naTEsa=CRdv&*9z898!mMm+c49(FPVSI0 zIU+y-s!VP`nFUjyAdHVgXE(#FM87wmygiEWWWhy~$+O*`tFMIQxtFN%L&xhxz|BXS zTKe#`IAS&U{niH$v@Blx?eT2!Xa@bY-RUaz5(gG%tW~}3?QI4vT*Q^3L}pQNmtg^B zKXg~>LO`Sk!=Zj5H_+DuJF2t*=3eUUD4XN{TsR@;`k>YiyDiKtc}@Z3V&$ExA)ZFv zb`U)Ki-5QIVWnD)4qxxCFrm`Q#?lobH%;)tPv{Hya?xaQ~+B2qQC%DSX$L$r#2wJ>d zZyg`c2M7OBE!Rf3F2eAZP>q{K;Ln;kmra^XOiF6i>-0~%Kg|o2Er*dbHs0X9?c^<1 ztsph{swxk_VF>^V*-EyROiu%LgJx^Ev4f;u2}ANT@uUjBqURHTiHaV(`z1>^SNFw0 zTl-C6L{ndx=bgEfS(E+Fq*9S`4kJ>L2r#!=0EkX4btc0fl{qRx?9l&CCn`HJGvUS~ z9TN<%LOgsHB>VgNdg@^}(}f}zwQ*D2LlQ6qVn6t7Fb!>p#1mlk>cUdf%f9XZfEI-V ze>2>wT3pn`l`2-h*}nFX4zyegAafrSnd>PGyrCOSj#v<3zu6JB15<7%h%@y=ItAhyPY3K0uA&pP5@*ejt{?vD0w*F(-*RYY=c+h;o6N@tDc?30P z;(7SGaEXR$svW_nmq3O`S3-r9-LCpS#z7Lb6cw|_^iuVCpeUc62bGkC%4G19q-0^t z+4kqA%~)JiN;Os0)uTMH48x!|qTwvz#xCQ}0c(K%NLJ=Gwqvp9K zJAlIFmfT@KDK5k>Jv?dw@Ea6McJ=qy1$i&*92%Y@woY4o|4=ezGUvLj7=;zx1qDzB zI?(U@P*hskf4at1Ya5xJyca{4q?x|1vQ%Rt-6P^SeLBD)2UNVn-#G#zeceROYegQu)?)4SLo zbUn~=d${Y|8CjT^u&lw|uzfswxPFAbY zGLK@6M-j*o|AOzx7#>@^NnJQlp^ZIa2@?258yqIf`*~|uNZd#*Tqx^aF2A$@xvb9z zJw(L7oA1vS+VtKf{&RSliE%Qu6xG*I$*Smh;l&nN^)dg$IuZ0uQ>%-!Giof92;#2@ z{C-P9=wOttQqTJhEZcQ>PL3C{i3;)22Idx_8?rw9@)?m>C?wb+{+*1iysHk4v9~AO zAO;=4L5~V~9oU(UMiwJJsVvybKo>?lDxC@u0rr8^2OSeWUSiGEVovMhUll5|&mUAA zYIcu=Zaw_8BVMC+=l80{zj1GCS}30{#l3-vwPt%ACZa@xMVhJTtFnK6iJg@_a#G8dQ~tO5R9X)(1GcekeVX=8QHkYV%eT9@H+)3GH>v4~Mb zSdj)J|L3!!OE;1{+lkQ}0~$M9TU$}lfN6_v_Kl&mvJsPRJ2pqCeKU{%JC2EDw~6ZU zMTVt(^5Q`%MSD2#MN~5wnM-NJc3(RYsy>ydSA9C)oyPi@3kGA$(9t%Y`4b>=aQJ-C zaI@=cgK6=%sDZ?qEqC~3Z3xO%OliA5zbV2v={?R63=r{zTx3IEsYSO?NNaG0n8FXN^hJp zSiGLpIlo{XpWId~EQj1=jeK^Te{Z$W6tW$m*4lEs;n`w0U0J)}g8HpHbZe{=rE6hf z!BHk{q0(eTm^0$AWZ=`z&Q9kh*iHDL4C7oXDc)gkrrP7~`bWVFS^@9h;6TU7f#2V& zCjVgpG8oCP^O8a9<40fEeMxM3?H0FsD$=i43C~0dZ|1Qk(ACy}R${ zy=;G}Nr%&s3WPNQL>^89-`^j!M%6q#qu^c6{=8GEkM}m+>Gr6HIk&R-Nl$Ws=Z{>> zFDz8A*YBz{>Zg!R<@!#AAlzfgoGUeLf2dp1S>doQH9@sbEy96t;?Dj$T#o9r4eq6( zK+N&ofhQ3^adCp8cpQ;qoG(a)tnKEx%Fk}!f3ff@%ERsRy;j~YD>XZ1t*#S=-z2@+ z!(I|`jL(hwMC|6|Ihaf>8ws<>Lr) zOK`A76W3F%w?+(spV>7sqb(rHSR5N0ohv?a`lO_!1jcUQPVMOE_+eLiW3 zwC2ND7ZReQqt6|1az0|787YwO&8A>UslbNIi%-QFH9x9>I0fPSH5cwjD!EQoV)QQ@ zow&s-4gnRf4K4RI{W8m&wZetmc!<{DcKbxAZeaA6XEXQc&hwZF^@(z)of8)mBPeJA z(5Gm{AD8y%?wI74L?6zr@?2cdgoRO3UYLGWB_kEhB8l(cJTgS}=~^BxnE03{GhxD_ z%AZr6v&QLpreeyQdSAH}^Yi7iXqv=J$qtUZ7O0vQ{fl9r&?42#To%xaTCh8 zsK@D1F=#HuPU(2A53oMJy2>OALO~d%4%FzNQ|UE(Px4Jc@oNfUbv20{a`al*&LsD7 z4*hdpuDcphu{<)G{%ncs_Z;Ri=YW&Tc7Ijn^AuG1gX~jM)RdIE3qDpOAYhcS8dmu| zL-hHOBv2x951*w>N{7SYZxkEXojGEJijzyyUQQE6p?7@wH{vCyPZ9tfC`f>!L18~h z|0&uZRX69V_5Q+hD2-7tV`Am1d~A!&onv@0EhQE!&PYD*qX`QLvGi-FUPK-l@596G zVL<0g+19-X={&N+-_S{No5w6bC+T=o>F_j3OHhUC?gY1MWpD_27{$UCEoKm+ua83g z-lT@-adev7-y$6)MBni67ox6>wY4}~G06z1qc?EZCZp6rL?8;K(Y<)@GjT^)qXw18 zvwx9zcC6R@a{ku#Xk45`LaJ(yq~~z}aPXg?Qdqr2zoezvn=&QBypm ze{~m5h%3wMxX|=N;nLcOE||~1g>a^Ae~Ylh{g3aWJh3$VpEFu%{HTe?4BQ(H!)d(> z$Fa5=FE~UPa*T_jXBWKJ;a9fcxH$9PoDM5cBx~sQyq2Tc<8Q9C>g~}e;plN&03o!Y)W@pKCqb@&dS5m*xjH(iskx!K>)QoS5mZdS zxjT**%~z9`AGy6cd50Y$lh>(!_Uy%L-Bdkzx)y*oAd3JZnN?HNxUc`LFp4iN=RiOw zje?UPrG;S?6vE|?h=?tlrme2PG^*z#r=d|aVYcVM35qQ(rL)5(aQ1`-L~_J<@N5Y@ zc>f6tzUI?e)JnUV6BB*WvVP{GMTdh) zjimVf`}a6{o%@Oa>u1oYZ8g(RjA^aPxiP9_k*(47&6;)*R%LcAwj)_ZF&nijG z^)yD5P(4&8ZL10qT9ZKcSlTGW^jmi>@K&)WtTk1Tx;JsSymoN$^3;IsloIOFV zZ1c0@WIEI7fY32iWOq`-sw+k(EG*2MZ)rr7s0-<4`0fcz9GgJi4=z!_3 zfHuD=ef(Huy)2NUfEOfmez4dIq?e7{}|H)>WUlS*WE!Xl9aN38ZiAr`HO?fOq1nphfER>#vDTiO3F zc_a1O>wbInlSVbOqPdxyme&04`mDY_Lp-`;w${;bAedTuZS*GE-TB5v@(0C7W$b0> z%Cjo~Q)02yR1SNbnSzKefPB-_)0DEQLP3lRcR`e?2`r|VH8}6=-V|^b4Gzeg*^`b^ z`$oIhb2h4kS=veTji({x03nQZ5HOOY*d_dvFVrQ4Z@JsEBI5OUt<_r2V?ZjwPYtHY z$;jsWfFCd^gREXMr4(Z|-(W=A*J}=isyYWC&?-%NU-pj|!{vwhh)J*2aGFUt$od{3 zMuK}%MjRr1aD+tnkhSP$ae3Q?L)c*jO((JgVDczsA{-3gJvkw61cx`AxeWM>97fjP zdUSh7cFc6f7Kh%XQLOlO=X{Z!|^lbvWZOQ5PnxEft+0sw8!kR`6BL-r* zZxy{+i$s-;LSc7et|wT@VFA#)#ohr#jYP@0zUfmo84GXmVHOA%`}+GUSWr03^$vd} zNIdkFYGt;kxAjp*kr_M}3$UHoy}CYQH||7ITo2t+oJ$1W3QbG1qHLtQL60^EWQ|Sd zGv>Yd>2)Gm6-7lwEiE3W!Y}gaC^?Y5J{ zwC%AtRBBUFURtfCc<)wMJ`Gjllc_lQ`TnuZ3So8R2AcE(VkmHzhy7HWX6 zjIq7tei5hReo+y#iZaazxm3}__F1a8H__cu#KYyVV3Yvk?P|dNVZg#hDs7O+7s=z~ z_VOjqyRytg=758?&(ODu)3t?4M6sfWJmu!p5bGX7N8QA$SClerDKepoYV|g2o3yqy z6&M*}nTt3etcb2kxBJ^p<3VCJz(L8Ev928H3X+J!Wem6c?FmS8KAbY>Nr&fI?fiTUVB`3g~D;^I6m8W*){EwzM&yCzFC&Rp)O z%t`xgKFUU9E5A+g5iBQemWc~FKGE{vZ4sU-3!EZ&gNrn6p_lhDxJ$;-j^*@B?dAp! z4o;@=Zs}xbgc=iFyJk;2EL=&c@ILAiNi zoCiOnPB!n>%4b6;r17Pd8XFqt+jaMK(|yv(ch8iuaR{FKo3On`MKqv^MGr!%423~l z6q(;=mRR%NNLy^O(m~E;Q7#bh@#6dj%ip$y_2tloCoK15u6{)G`^}?yV?s&VQFO?^ z1hINDV`It=+^T6e(}AJ!i6Gn*ANx0qjEu*WJd2}OC-xjE z9QeW!^mtza6@p+y0QSw&5vI8V1!a9Og@6X~GZITfN9XV-av8Di%WMONE!>)CLL>eu zS@LTE0hO9AraVwSgjgKPJ&OyL<39PwK@hGikwTFUhigq)o@l`c*t|M?aIkROOiDHM z5RS21IJWGw=}3aq(a}+6V9uK^ITIHna+h!{BctkBi)}F>Ah*QAWunoGr(Lz4v%T4i zmXN@tY+rfDd)cS5>w7}_cgRf$oy%t!A1zK2j%EUKN{zw8Ov}wqArLW zikI2gf*3f0^vvjE)%Su$Sfx`M*18E67yTZf++5^6h^XmZuBVoo;G;Uy+u)HQ2|V0} zwE=`LAY?>e>JMKsdtKdJ{}fx*@w{kky&QUQJNg+!7XX*Dv%S~sC4XFBk79S!0TZi> z9+D=dL~}4(^Vz3wupg@H1YCfoqv%difx2`)?@&zD8k@Bct0s~Ffhd`PLqVhfU&~r$ zu;<-L+QD?=#RYxq?F}lkxL~54lt-{ zBlgKXGsC}l!%|kP1 zss{v%*3v^t10W76qB~uD=bCU2-Ac-d`&!qQxMe6=@=rCvgc88ifk9YP|3+&J&k zZ-lSOW5hza%mbarsGwJsM~*0GCH50q3V}EscFR>E_4V~vS66{b`z<$?zvXT#);fQ5 zHFI-+%3)$*KtH&6Ul)j?9Dt@;GDb@?th8$|)JFISbJ0K`yfyy481)hLq?-63*gM^2;LpJDEmlN2pq8V*9*{i@n>G_C#$l_aFVsXLyDnBx4Nmq)9{Jr+`rn z9uW~S)p;F{Ov$qK?!2$BZv>}**_!J-;=!c2R5@`#A`8P;$>)AadTiZIfBE-F8d>Ls zP;mnKQb01=gShV5M=fB23e5;=9#0b#@lH-o7JcKqiX!39e*y&5{HHe^ylU83J{O9Y z1M}Mi9zbbJSH)W34OA?|!U#a3DohaG^+YnBg84A{ij;dAJ-YNSgJEeUqDva9YHKDF zQ?WjkKxgds6|nLMujR2vo%4AIq4U*}M=OWC(E%yDh6)*~jmB+~NspPAaln(fOk>t- z(uIC)=ezB1>7#tarF@u1j~tWEia$>_Qv(uqb{-%k6w5>U7MQL;ZLj9P5*JN5uVPXRZvjJ@Bu1ws9we|U53E)weMK5IMDsZ-~l8W-9vH4 z|0*S#L2awz(Z6Ywer`mwd=H#`wTl{r5({ySpcR9RvP z@p0?HrMG_O{h3hbSeFcAeAkeSlJ<|Pk^0e=J5eO~LX-t}Tt%u+ErAkA+Gh^Z^F3=M zSE(p>-u*)Bl@^~il)`JfL7S&u%n?RD!Ise&;0jj=Ou_ogQNv_2Ozm{#n zc7&a6p!@t6F#zNLgFev|A%2ZAkY9@J){;L&sT=EZ`>Ly4#<8$;pUL%v8v4W*dD~Xd zSP{1x!4poPdN)i?#=jt}^zW3A5=c%WC|5soY0g&2xQJKCoBgu#^EyXzEHkqhnpAs7 zfOSRI-kM&59v391D*(T+(E1=s-#lJ4Le<~*byQ)jSS=xodHo`bL9CEibIY!tj^%@l z*t8Q+ynW2sy!+l~t@}Ms{gsbO8gHim{ z!>(FbgoX8L2@Dih8h=$zS}b^69uAYt0d9vXG7eg?h#TmWc-)L_RG_;)OZ~_ zV2fn_iHldcKkUTnk0Y08GJo)BoK4Y?LqBqg9D`+aWe3WLn~uMRi8l-9`ydA2l<^>3|+G2I=KnGzaJd>}rk#(R z7%7ujcP>a8UERoeaI)m(V1l<@Uxde%q@Qv~a!|S)(z5l>gPvj?^6BYtIV9A=Kne12 zf%x*={rxWxa#^6JFQ=OcxC--34X-KaGJulXtKs#v=eUr#*x2(I_-zf6%IBZvg zw=Fc)Gou4ZwjsgTzmxHhiJ$w*(;Vs1z^Ym9Y~peR6F>(Wg>nX?#r$f7Pqy#ijb%QS z%H!U!f2d~<@&Ag1SOi(9`!bR#EVw3eP!_=RaCLLgcyQ~73h+@JDf`4N2i&%L@hoRQjU&FMr*^~@$go@Po#9JKPIy@zVY;cqZj&%XM@!gfPon^2itve#NI@&JQ16)G1EC9{82QwwtU|1ZLW z766$4(XG-%nLc55pw)8QQ`SuJyfh0lLW!ZVLc!FLt^CVs?>ALQTzvcnkOsw}y%Zik z=wGuzct-T@-Mh<&LzS(^=7~fEfbdP!2r&AGpp)kJrr^~vWg?Mizm7;rNqH9jrfbO+O{hW@qFn}5)f^`Zm4Xbo-VBA}F*8Ih zSk?|Dv04FH2vKr~2Gmrdw1J>;lojJK3;@6Y{p+hdnLQroO5Jk{yc72>eI!NF_Vm)S zgW`d>q@)m41Or6|{g%2qwhXKg5zd*}6dB5u=-XSjN9N}L?x@LZJE}6CaA^+p+n%>% z2S>4d=TnJqERxI_GcqzFO8;3LLHBlXN2Hd_PAvC2E~L>_<4s_Y%?2`$X7xAy0K zl#4>TGQWv^6F5q|Igs_lp9K7w*hj!mna-3KV?P32c03=y<^I;WL#%e0P%FK>&`_xf zP)VyNebF;$fku_C{9&XYf1P1c*!RuJHy@8o0zA6~S zVxf+4+ghk;A#f-FoqX5MfA8FDg68T@_F>BNF3mU;SYB9gYj`R zv_YNZOr=j1|8F@z+rKS4Dr$mOg{HFVxsj3owwZzbdkX3gy~k56$FcMa&UrJRPO5(h zaix~`W7)7Bz6YoQy1#dnGT9<$suIvWACFYNGeu732E|CI3vmNs=bhMz24F|KQ2+I8 zB=-ZMj#$lC<`g$+W=){rhtbi?g1-hX(qFp$frZ_Z#`V=y5Y@On!L--)LWF z4o*s|8I}t2jR|PTstF~+X>Dw*LAC-M%v-+g zrmd~rI$>6=ddTI#ml!F7{Kw*>jcxopEtjz1-hN=6;JO(omt8|O^h8vG>k2^|gZ8{9 zpXaOX&hj+%X8%DD5lZbqa;$(#B2 z^*B(UvWf}to|=2@qtKa5`g!!J+Zu6Ar-nv~^l@3X@RGt!vLJhm-fQv*i35*DbnEx~H+7`xHXLqwHXb*tE1VzBI?2qiu>rzdcm+#V{7f#p?bvwo147?9?4^xxi|Q7UBjS!(}I<>U1_5I3Zb#V?A6QdY5GWefaza=v+azmZoN<>;lz zJVBU9vQCNeTV=JD*FpGC%kc-S@;~+FQ7M?KS7aR5Kz`%uisAC3wsvEEeQlNM_a{@` zHfnLP!mkJQx(3%A0mR5FwDa*91qGVaM=Q1Ogr|E)t?I&?5RFX<*OcvE`5` zq#MZly;m^+jsK_n1Q9v?FSbuO;NpPpAfOF!-f^*6zYAsjVK~D;mg^{4o4$`pKQ^DZ z5v6o!A{LAk#k76lmm;I%cyXsu8!lpYeY!>8e2VEmZq9-)W#~4g>iz`#0vWS+&mfXgp9qVU$_}Ds<99)WoVSZb#i=O5S{7R4gI-qUUqByH{A5 z3h#v8Zl10k>zMgG#d>GVnZJY?6BS%$Qw=h)hu&iyZs=C-5v2wpZ3Bi6xI*tU&q@vJX z`%mVf)f&|rrYi8HW(cf&Olhmfp0i|{XolkEZ~hSF*!So^rWqoQ;Pk;F)QM+*+h!Dq zZJ`Oh?QH7%rzkBO%gOcOKKesrLpmQgE3*TCvlgMDF^p%?nD?xpKW_T3wUb4S9I^GZ z$`!PY)LRjV^vSU_!i=8y06Xl>?H$*n)2*gNW-K#%7F?uLyTB;$p^NeFq^S*Ssdh7( z&Nm55PK#xpdy7>);1{COxw}bL+6=*oApt2~Nslg7(aS(F>W7}{W4AB3SJj*7Vc)S? zBrCUEPLb+XOKZPdL`yt~f}S4tg{zCpzE+*}Sf+509&UxnX@o3S2Cvg0N6KKRpNe7q z;M%Ci^_V0e`(}B3yr5o28ocSUzjHK77p>&@{3#0b&YBwCtSz2dJn z+c7nDxbAH+)6@PP9k-@q+Jyz|9?JrmKF@LJeh~3kjG8f;anbZ|QpkT#nZN2LpbH_l zM^Jstw4hD4x8jdB1C+l*yyh)E*XJFjjf|qy!+y0Q%A^YA(OdL>6Jx=R>C{_Ai9zht z=m{tJidSd7+}2NDBs@Zk6exN9?4ceWw!ccXp&=?q0`d$hX<96xYmzqh?-wvG5iI2G zJMk!ijJBzxde9J1ASWwpOa0r^)x@Qwj17tc-0+XtZ|XsQ0zm7^q6Cc+mkBaF2gsY~ zes6J*&9PKDhh}68RJj{tR7?C5JqJl34RXU)$m2|qNDf3>B0wl-^h04T0`&JCdPvvI z%#6CaI?z5f>BXEVH8C;q*IhmpNSNz_K_ezVa&x=)9R6x|ju(7HMMdqgvq1~t9hots zqQ`j#7nMInfQslRN98XhL5$wnswx%ORlb{5o1q5;P#;?l5l-rD1MYWPD_Oof6$+!@ z`sm_(eNj?Vo~bVtzdrbA3UWYnh4}#`Bqj({CqA>Va8LAbLFX9NSekSG(Bs*`ndFSTlf~wV{jNoYov=4rV5uEhk zz71=MoO?{a-@npbj4~G)K$X`egLQlDyzGaAo@r98?p6scl~7ajvoZv9GLGuG0i|j& z3fSzA0vYK0On)ps7^;*r=8iU3+U8NPswi|HkdVq9on6qUFjI;~`6$yWyQ0nRkp#eX z?g%RH)C?rOGL92E8aZ&6EiL7F6*Ru21NmUJGil|vqaoqOk&)kA_6=l3KA}wKhWEEx&*|?>+9e)n3q91-QK8KOk)8-FS`Qr$m{&cCCI#Z`#NIB{HbnC-)&^&bq?AdtPi z?2#TA2>15B_3;TlKF)}*du$la0UGGD?M^BVx88bbYi~9&0to{=L#!&{~o2o ziC-&5z0crlKn41>L4<5om6f?tiIp~M605?ZI)DEf4>xpa6yiQ%RzK>Gn*wJqU@?+|2{LONL3&e+DXk zH8t3HSY)c!qUS)V^@l11NC-@|os}a%rj+UOMJmN=Cod0LIM;?VXngg$`eHYKJ8zFu zlSwjOUFJ-5^}06plVgE@GSm11gx=@fDH9a;7LCc0Mmx`^y5=kR?wI&Nc=X9{pjU6b zz5=y7p3)Bvtr-wVaRKo>Iuqwnj!9&nK34@pZK2x?)YNa+N|ZU;)_*7V-xrE}lW*5A6U+OlB8X9L9Xx6>P77YVJk4XI{W3ZpgaB=% zww6Xnkgw03Yr;hk!LGYIpFJ{NZ+}MgQ#2Xw*^8#5Zi23^F0mRnMTNDJ+J%l(u~uEy zU0?Ce;m;PUl7~t_?>0V?P{;DaU6GFX$GmPA7lvPK*fw3l&kzyuXJ$%uY6oNdyeV;b z1(wT!LPgmjZkRqI1AmTsVtjn3j1CUx5tP#Og}+Rs@WoG3l17I8jT1w)(H%zcW#epf zBx|!O{477Oxpk1`6Ku%h7p$);I__9nT?|gF7~Q(fy#U!vQYijIy&UZulCPzmwMorN0pQlFTX=cj*mTt1_j}!7) z%S^d?2St1|Xsko>e84O>)$5nxcOG|+Nf8q>Q&Sva-w`U2tjqFOK_Vx%wvC(|hg*5+ z=`e8W!-8mcKdq~57>u2?F38lT)2Ecjfm+!A!K0dJIboU$d2WI+iys_U~3Gd4tFa$HD`! z9*Johz{_RnugHKC&|#&nCKg7H%4B&{)=uhu+Fx-x;8IAB;)cCRvy$QWevi(80OCn| z8IAvzt({ow6t>eqAh<6C*t4Aoc4qIf1^9VO^93?kl5(c2jEW<`FP`08%lxRBY|xZQ zk%2~KxsWXRcj9_E3h(+y_+aFN^A+?a>2oCPGjb4GmqdK^E)(mabQ7^Hln#>7sLG|L zwjO)Vsyes-uuy*zIYqm+;cDNIu1%jPmFLSJrmTS;vKB(B+|iwf7h2!ra*i9A7IkKr zK^>_LqK&72m^kp*sGVjRq0)Z|{|4wv-?br;yK1j(4I@AitN&qdul5YlMMI;}ohL`Y zn*otiNHF6v(nYPCgGRfS6CI67PP~lhIW)(`^#$T#M%^zeD4MR`x@^TN1q|sQ&{3$R zDExr^{yKAn%7{H%PIvkGx`87!uP2k%2_Vj&U*`LUnd``Ce*^rh*ir?(`&IzZRH`b6 z&{~e9nCa14((Jy|9X6IL+wB}v;+WlVDP>aS#U!A=K1w273Ml^-?P(5uc zv>=>yF?#(q=*bca0JVN)Pkz$+CshQNY^lgs$UQ21g+hm1|v4#uiRa6LoGQJYRQb!1Hm$1Vf^bKg4`=)QrT@= zN@bK(ap_wiS++>~{iOQs9cP!ydMwwOBYwDcyzbWkLgz^(GAT;VwXHeDl03JRTbe=L z{Zs!jM~>@${-98argc$AQ!(cA2b~&R)!nlN4NGVH2M=k>($XJ_Mjx`$64ow{N@$f2 zCp(S0E`e}0k_1S0nX)s~2F%}ip(98(ktp&>z|$(|Oy@mMhA+TG<7wYUVZv5z8%6Q( z1ZTX&q``mggMB-D93*Rz!0jsG>`Y2(W^Ue@`5d=0Q@JQlCgpo{v~7v`;0}=I`* zj9hGWKHuG@u{*xL>>-@3nK(N=r3EJ((0ULEpq~OK>IzHmFW=TbI+9Z?Kqf7p`@c&k z!(dCbnH>SuP`+R|ZsEGi7nDMvOm{2 z%xcT>3p+?@u&}UH?Q%*>2e<5iy0+f)U4x!*y@hh|XbP=%duJp7QjI`_goIAd+VDj` zBz*?DQnPr2P`H1Byno_i&4mt|*}GbBGgHI|ACx4sTr+=pY}hj;1=u`jJ1USnhFW?8 zs%CtKvl5+|Nt&%ZjIq-Pip3ktEm(Bv52J2H&m`XDf3O!9n9DqLx^;KgXUK<8Ic=mk z9{*lX;dDH|xFA6DkBY+71jh?2s!+rur`BV=rLfNQ*L@)@F2ksJ28y|v;x7OPPw zteIs*MZed3`)848b5FSVczA>NVfyC4a}!l3fzbfbhB`3Z`W4Pp7iMH{>C)^^6A!m$ zA4#1v!8e|_M_RrSMIN70BZ0CH(9?6c6R~)G;u{echYjiExb~4QE5u~f5Fz%;Mxhvt zj4?ZL6J?pXIUV!9zAiQBQNOuK392Hgy#_MeWmdw!!;uZ_&c}vPx8V^jl~3WX3DB%; z&LS}v05U*tBRvxHU1Em!FIb{|gCB;-2v_;qfUWc;4A(%N?4nG~oV>fI*HIk=VF9kzRdheYiXLdwkgd zoB;`fJS&s-KEmkj7bKEm_5s^9?e6Xhu`%XOLu_nqq$G@b|H`{G115j%CH0Lb-x_v&iM zvjsR@YWKTsBj_2C8+rx&NAC1QuyS!- z{)VwKa3K-|DjXI8+k3zHLi?v!U<%#L)r@C|*XPYlfTlY2+|;lHHX<@?ZO;kL!>Mco z^~dt$A`ad~kK(~fB6G$8EcoB^@#IKOaO}KBeG8eSu+cGDd3d>fZM`gRcQaEhBAv@1 zK`XY~Nakdqg-ndyo6*xkq8`7p4UDS>Lzu&`{{F~*mAmJ3`)o=l0%>_TL-1&#VBphF zth&C0L9dkA#>Sx^wHF*I(G%NBAvins9CqRl`O(DRY{sNnNkV~ki>~>}+uK`ukE4*F ziZden-uJE^R4Gw)q|r1}QmHr+?_h7k8Pm*cM=&P9v1~4Wt-39C~)0&Kc=a>&D&?O!_ftA zrwjICl`*k@FAB9!%V;+o-Oo?)zQk#~%(5=s9X{Mrg|P3dd1~7S`@t$Lkg(c?Jy`OG~;>mtA(534bnVl$l;n z?k{|HJ)f2{-uMH;g5X{KPO@6rnF|g+L&edL*;9f{yysEUuPl?Kzm^};X`oEY;1fZ1 z+Zs!Ip_f6{s-qz3N6=5Mltf&M#MDwFq0rO$axrJZj2Y!?EYKasqzoW$_Xqb}6|NB? zn9eyy;};@n20S_z>5JeN?RWT6it=iSyv{Z)6J|RHMCG$1U2Z=jR4(@SE}VjGY*~M& zBz^9%;4QeWv)~|?$D>eEsFqjT|AI|LPv2^~rJ$puGrlneHjJNd{NZG4x?tm5!*znn_ln-GmW}Ud!6>>Js%iAtXq$Q9jWTUjr_Px>Lc+SVv_nS%2@=}b)xcZw)PB%-D!&WvS>UQHo6LT0<* z8kZy`DjzfNL1H4;sJ=&yFGtyPhgRpRG3^c#dIL_FapeOW@+ZYkU?6eb405K`U#)*> z;gOYvM)lP2Y&$9nEO4ld@*q``quSQHcN8}gzhnHIc^C<>uC+qt-bi)(9U`*650GVj zjRYJ{o$RBT=$o#3)w4hAcpXHk9b*I;^IyxPL=^}p-prEU@j)m(aLeOh#gQa!x-i+_ zyiA+Yv2tMR;LzfWvhziK?_WIGI9b|!;!m)!NK5{}``syG%rnPuta5ltXlZq8?BRIM zw)@z|uRZ-|7*-Wt5#P-04A9GBrO|r-9ZaG`&vd%psn)7cjjU#gf`-BX9Jl@&ie0zt zPkP5E%f+DffiTlyBa z$#{gccGh*Zm%3PvD6H_AJL5ir?^Y*@@Z{CWJm4X>=smu~3Sb;KZCTfQ9Q|f?5A-;7 zDVer-eM?O0!j+)ubai`0J^z6yNk)7;Ts$_$(g@o_69IcLt+l>jD@QQkxUg`=8B1IN zAkO1rn`dV@ib_7a2zS+Kr%*!KV1{KNT&8G3R`o*0P5`n`ffu1F?J+uK&FAVsprx#g zy$;*>L$yx$V!!b~Kd#)z2LwR~%bCQc(+uo-&DgSL%zKmQ(T%27vM@DccINa(vx0P~ zr|uR;ISTxBX=ywYNs=^BiS!#!-k965-AQ)TYulRpHP*%5iz^?F6nt6%v+5}Ik~Yve z2ciCVPxq~y)~20OP}S9FRQ6BiM#lq@8bc>}jA*i!=F_W?R6GxGEp_BC(8c^0QAeu- zgd!ykRor&hNQD9>{OYc*q21{d-yt`OXd_iez^qT?~tP*z{gj_f37Txh6vJ7De0Ts`6etLnsBhWNdNCI%*x8LubzThyb)ko-4wdj)2VLz z?47?85sFkaE)GPCNp;1^Bc5F_RidDrSO0*ReNN#q>iZ+ZQOD|1!E>`))oZvih?>j6 z1*~A~^!0H}k7t90)$(51bIe(BUEQ8|)_Ax} ziay)tBn|Nq57VNHw>=zL7+DS!3dW(wjznxX4s0*>hKT!DD%=Dis__{=Z-o>+OH*FH zrHDQ~?DW)T&q=SyK|syE?HuxagY2ijTpoC)VThN~`BfE-NHkLYsB!+Dp}{NXP$7bP z@)kme5G4YG%CY=e@8R3qO}Su!t>6%8+jS=mjiYt13%uWI#lQPTv9X#xcK^g8&;ZS< zY$b~aqS^=tGDwP_hEl^!1)>nW9?39t;8aIP8XSt77!30(10MR;E`7*5rKEwrT?;oz zWLS3^&;Yvff0%m5=sLSE+`D0SY-`7M8a1{WH)w1&W@Fn{)7Wlf+fHLUX>7lDp8t8z zIA8K zhINgi6iLJ(>{Gsh8BpT$8%5)O=_hEbY7cJ$DdZkoh{HI%gSN9}4JEYy9B5}Pq3Ou_ z>nu3_@bhaxlp3<_VG%AvaeX-#Fs;$B>wrnXHVhj4}=^J2aL;$^TWt}OX$ z-ICw!@psN|RS7z%JQWJKY*@PiB^|}d6Nj-ZzK3Kj8y>fFFx9Kbx=m!oL}{hk?oMbU zMp)1RT0yVb9$HUy^{%gEWJzt&ScDrvw{A8szV08(n@GGF+a{A4R0&Os!!ZI*zPHP-Nbql;r)^BGH8Qr->%`wtZe79$-ZwP8|ZR&Q=(+K3;t%GDyC%Xz8yn}|NQzbsBfe>GqFZNa_sE&$uiudjCiUF%)tXBrAU zFYkr=$SPp}UEJ(0s>p)Tqi(Nn@#Uy`2`+@m{XW=e^&6oW%V35RhvZogCuWwHi$`E@ z#yq-qJn4+i1Rc6^JUloUDm`>*z<6lgEs~x3R%&GNtK_likl^F896Q~uyPIu>6rE2K zAnsC93YUFFgD*j!57(ph=Bb)_I0!&7-Nb-;;8>t!FY0#L|*yoR6=q|4fJVi9020^bw7cv zSkYhEyZ?b=RN7#HMYQ*SFCxUlJ=kl}K;Gduu6|&GhW8v2ja?(uY0Pr}?CrEIk$4#* z_zZ!8S9W>nfXx&sNefbfC5adLO>}hU`tVhP$1F!8$w(wHpa8`az7IvuyXjBI8`%*O z0jK9noFo8)#rgStfZdhc%2Ul{n)k}!n#lfyP*$S-Td)I&>!vk+73GN{hOGMQqXh~G zvqu7xW+ny_lF_F_farc&DA%kzZQPCq zfNZubHZ`GBAlT3*0P5tGQS4RmY><293@hEek`T|k{gM!3$RH)ukPUV}-Q*E?1SO0} z(LSTjZCdSGiu8lpATzWwsrafoF6=)tmb6d2N?Atnvvd$OA0?Uw9a!*R_SJPC{ypAA z2(IKD2Y<;J9vRm4-o^3(E6&U%HF&>3=3TrxAODss${$rgLXZJmPr%Z`n(}g%0=`1x zs5T&2R~J_;4*YWXh{Lce(@{{EVehecIwdxuOlq29S;fge&#L3YV%e$brK7uty`uZl z+Pq38SHKQJ`703gmev!F@XJG9?T$qkCkr9+Ex+Auc!pbEg(gO6N+0UwZ>|NSxd{Xqj15ZS!umQRY4T;wY zqR-YgcVBu;A;n1$SLVf1>^)K44dyEwo}T_-VOj1e_m}v&e}ku}>6|^BVciez+l8lY z_JtR5W#BYAUGV|@atH|Ufnv<6_uHM%4Sm&Ic!_{vz)ZSP=@xR4W9Q-MgWbfmtQFqb zQn*KJP50?P_kWe|?8TV{+I$fiy6U!dJ;wi{!__V)nDx z{!M9;47E*4Vxs4fO15&@-27NSgTKFgRfqdjZqeJlq!&x5HoRI`Uon zcW62%t(UnG=6Mf3_&U59=RhZ3TtC3gG;-TQt zqE^&mGmKfVPU6VDLPUgMI=ayOUfQp-3n+<<$-e9i?YUnC=VCs$#W3H5?kXCx zCUyB{WJz`R<|XF%gsQQGq>A_{U^PNDchujOaIIg%1oRYCzx^vwX{c{lf82_|M|dp0 z0*ZOYnVqfT5wAx>)Ml&hMfQueyC{6;y$K4rRtI)L%Qmg{meSIL$59j4htv5MHPlQiD{a)vvb~;8?raLRe|*UP&vFbJz*;GU$*Vy_ zq(G6mI)2+PPtuJf>cQtvm&l?&+Q;K2Xl?(Qxu3=z-h%B1%iF;heiD|#A^mFi3_ zAgXSNd89wVw6dX^AqTh~MfUkH%Lvb*OJi9ho)TtX;u6$oc-fvQ03>D(fi1)6xcmpP zys7%XYS$zx3n$U_oTB0|{@FX#2DHHE--G{rt&3WVcqbt;NwyM^bW1KSm{xE08hf?FK4X zY3Ee>5L6l;F5r^W0Cs(W+w-2~hbLo6X|wCG+UOGCU)5qcSK1eWLk{#BU&M7<)+{h! z%e4kbk?Yz(lirtADI3%)CQTL7(kL308alxe$mAntpdu=eiG}Tdg;k-y4>Y)X@D3cu zU0vnI_^aKc9RF#5yeT4Fq)Y$&eDnU{;hjG?H-K1yE~zY4-X0SxP~P9&JdyfrfgYUk zd|AfcsYMSY318JhvWrjtUSaWKG8_gt{nMO@CGlnfxJezd(tFWbm!^Z$Iry*)TS1}gFsB`juk(qYr) zk?W~)6wB2mQ8GNVdr9Q|hRo$v!^w*qkTLaio z%$=Q7ZZf7kpK=X%fS&-4>YeWd$=0nfb}dtzcK;S?jDS)r;Mmc(TP?!AcP!THzcVDR zF4nS;P$oo)+ma17Ks*-gR<~ZI!VlB_hn`i@uJxD z+{zHDt@m|*Fs{{{L$7K8ohdYvH=wKb@iEuuu?SXE_i4fC0Rg)g<=s_n&<&y&%caF@ zcQ`4+srfQJ9f$Wb`QYT%7&SJ#u}PcL{rR}vLJZvB8k@Fv+|Zp4i#G*3Ir)^|UL?$- zi$#tJy{iS=R7X-*{NzSW{--BUdIjw6jQJQLfQ4=h7%0X^R&=xJ5J2?80pyparslzB zlpQ%Wwb|v)5N>F$kibrS$ebnMsd9@TVq-#yP6bl6<8C)(v3l+|=8hE4W3{C8?|5nC z;<2W9QH*5$?T7l&52^BeO!BEp(wPm3!#aR;G0Xz5$)nMo!&y&OR4g#vF7(}D)ukq{cy z1WaYmn*|a%rzYu9Wl@BVNYiev|A5Y{v02lWN6xBE9EW7eB(ZPHjP011Up<3&<5qnj zgW13mC)iaKB8F{pZpFvY1xtM9N+H^dj`9t*C8{l@8BJW=zGlKkvMSm^dKe4ZvvF`B zp|(6m>?qs&+u#VjUaK1+q8mVuf|H<8W59XS)6@Q#@N11LsZgsnk{fT{iZ!J2-^B&RrnmMdYd@ikRoy~01tzAo zspaDy+VfB`k(9q}Z}_C}4jn}N{BgBx1tUSlk6 z0EpFe(H{fZeb7Svx@SA-SPmEw36CdUUOJjhsL5wNrcHSE8`gkpB1`%Ojx+?`)gAp@ zXn}hUP9@3>XId5|$U#%E`z3%gY*Yzc(uHz!S}*w0hJ{GdO4aEH8$Od}vl>Z|&9LQl zkmQWiBx7f+Gm|qY(K+|^`Lzo;6(}A#mG+W6<pYLydONN<&jZwW8*VGfII*^hgZamIMg0GH zVPf$5QHk%JbsJp)AW{}N7@wxAtEul#0U!O70ZTe;SyzK2tT9<+ylvkYJ?ic%ujaM1B6R4{OnOvIXVk|EjV* z*#w{rTUIabp6DcOAHGKFNg8TK$)Gsw=Z8?`>Q;DU zB_kF@|KyRVdj)Nz0&#eAz&_=E!SCh5&vZIpS`=mz==hI?g#K`@+)*NfcAZ{?FDDl_@x+20r^U3>3tQE_E@*9{GnZs{Vym zfMhYPbGPeDi3c=aPxztj9}FZQ`v^!2QkMH*jE+S=O=wnn-nB%5X90ExN`R!ZmjXn& z&dv|8hntM2Z#AyO`YuGfs~v6YCttLFi<_wH)G`hwM_5-QaoTJ^7Q)ban;+?)sb(y}$ae8G_7$)nq4+c#hv_E3RD=23j^ds;c1xEwH{p&^9z z!@*!NlW;x|UO%Szhn5FBzO@t?@ln&+j_M?8x$v1YF6snRvY8&4+Gbrvw0MCdIhQGY z2J%EH@foZoN|_m%oXtdkp0-vseS1-^YiB{ye-;%BJLw+uz-u zByHLucjdDNboo=p9sK*(3!VHt1UG}JItyku4<&^$yztWwm5*J?)Yg=Fzbsxd7EI8u zGitxQ{qT7B43AuMJ-JBeA5sz=gi%=QYA`juBjf(XRG;X zd|o|gon0r{h~fXL6CbYj5oGcFbYF3xO(7vYXU5bJp2hm2KCOvxiiSB+jegk!|980{ zND)G})Ee^})=ms6*!<``@4J9QWMeZ#?{)p{ z`-Cy}@~WtNG|L$_<*N9#Ou0sg5s)Pa&B=%S@#0Wak zMEz`@KOUWMU9!%Yui`>MnoCO5_Bi=t?!)RZdK%J{z$XWMT~c2`=WVYK6MA+{f79iH z)XcK`4*U6QlwXF8r!U;1mn$ygfjtBKP8hhAG+`8#LWd>PjeVcF%iSaZ!)HEi3h}+p z>iRXdsi@sI`Dbv!+S<|~969(K7Ym{>t&Fdsxd}I+TBdj5Ol5dD5X@KB*2?i>*{~In z`8ky?YEF`z#hA*u?ULcX{93ebSorvzhd3idiZ0krLIqP?OLdx`et*y|-yc#cqQ|D; z!PB&Ap5MpYcz-;7c$k{lhtNUXdKdtsTX8XR90>KR$BVS`nFxdCBB2ts(V@qAAqhCG zyAW7w%)X@gjuHIk^;*)1o|k1q@3P_%*{Bnc!t?!a;U$E2y3wafw?;Wpg5+GGHG0)Y z({F+%yl;n!e)2B-y`8SqacK-E(lr=(!5P*M&jss{D)fWt%%jLXl#=g)f8fqShRGC{ zgq9&4hm;Ws`Jo)A&lYZ&Dhg*9yUDHny7Um9@C&-1C+**WT~K)=ytE_fsHt*^ zh8{@~XT#?cm$UEIqmE6(^mN)x>K-1Sr-*Bc)Nd4I6fwKI-+jG{L(r5A0Hdu*tP6!7 z=<>>7kQ^4Ye-~=KLuzT-=yy)r*)6(mJK)~vh-0qrCNlUvN`aPj(*G7A1u58YOBzzS znTHEipVsH()BK9t+*j8X&$>@ZGSC6TtpfO8wqxkAM|!tu^zB9|&}rp!AafKUPs$Z( zu#m6(mJ?qP1iA2eN!#-P?J1+AZtm7EkGr9xU0?q`u@61snCo5$4c@UqyOi z(oPG+VQDGZblJUO0UjM3TxO3?GdZ!*CsMsw#xs)?&#oo?QHh$AE_R8i8v8?6QI+bZJ=`n($~g`@Wvf^ER;|bMxwO_Zq4z%^|S8 z1Yo-{zCxz?=~JL5nm2DTFcKvA4sjLO!=x@L%XSF=Q1rH7ba+7*TQ_;SCP*YU{mN{mXUbxXOMp$tOkhrF5 z?fzbu#(m?+h;p1$^+lTBNeXua;i*g+867OlG~Spp>IkA4hf&vyJ)O9tzi@rSAJW?{ z1=e1`;TFlD$!P#n`H0Cr20-*wRwfa=SFto^(z9 z-=bZV1kQp*A6Pbji|`M!p4i9PZy6o#2b&=cCrfjjEWSsx)!Ka^E7Y^I2589P2-ak( zlEj4KTWG;4;&3Dcj8FF8E!oJf2lJ<2d9e0emp;1wW6`8jo+A5WWI3pus3`7(s2RRR zhueAJNmsx&nUt9+WP9exv3p2nLSt!VS?l(l6}LHm$FZkM38u zC+lz1<5^j4ZRL*!EVxZe2ncayy&gX{=uS232;JSI{rwFz!&${C75xHn8N?&hFpa== zT3_48%(@%hHpV=xB3G z%M>97#g~Ag{^4FmZ+bVT4GIG0n}q3!q$d{#=ac)IwA- zbO#X(o8d-9+<*m;EDr1SbNK3b21L-bo%;L|fi0hxYvRxUMduNq z(D|x5Q2WXc3DV9-;-KP=*M)(~mMwVgpu!#lEn#6gT(LR$tvCsBx;VupP1ur7^^~8j z*wu*HxZ04s5Ku~xX_>wjX#C2=%1Da|2bMXeHFuvMQuxVuGS4&+y{9)-UlF ztQj94=W*P#TUPm-BJzHWJ3$kBAJKYv3owPv3{li#?o^JOI~j=fZv{`O*I>`y9Sph1Y7IPi-plx0IOPcxi~`Z0BvE>tfVR)w<)zQ!RFxc4A*0dpTT zH;Bva>mRmWcP;Y_TETSl&CbVQ;-J31c7Oj@Kfk|~Omc4laf9Nr$wF@FF+^6jHoAag zUoxYX%jrrOILPL2rA|azI5zTFtR&40u!&e8fo{bXt#6mu%z%aAIh6qv*}|Oju}KO~ z|II8{5H*D;aHc>AZy=$f=3c^n7%~yw_yV3({AS6_c+>WL*)x(t64m#w@tH08s@Gc` zFP_v?$ss8&CRw&q*$MVr))T$eK zsRv+KzZYG8*KhHbv&E$fk~EAuo?FRbSbqa6+Cq|8kOALBTSz}MT{lvb2FaymojSA6 z2=E6GTmh?IUO8*JuDZmA$y`%K9BBU~UUcNZZle<UJlFAut5xSz7xSUn3zcB0=Fc4gjdhVwLAzOGwyP zJ*Bwu3D>>-jF;Cvxk4V?$c(WdZ$VDF)NumWp1%^9l10bsMUfug$YO{7Ep@D?%YQZ- zb4W_kB#VoeB-Wh#n@kYXaT_8?k;0()(lp`z{A$7T3Ges+J|^#ZC8B=52CAD12>K%| zdfZ?aj-F~9rrB7jUR$%lRBq|zWy@L1L`Fv0Y%^lJ|HbDw(Qo<)gh}8&%dcHzNGDYW zaMDzHWHr6pK+)i9u+9NIIY+SNVt&RiE^Hf=KG@Zg;!jwP!OC-L>e=iapAys{$da-U z8TwF1?5Nf4S##(@KynroHdAgJLZ7`mFE1PO#`b$EP$e;k6nWUG6M$y-2MIAA%XlaH z|1yR&;SWKh*trx*iRVdT!|87$db%tes%D(~S{2YXmTR@UO}1XgMC;Fma|^EA?4t24 zaxl>6zW(r){|LVXnUNZC6TM3SM8z`M`(%(g`qfwGn>TMy9Z9L(ch|kshk-Ta1M)Am zN%Uq|IB)-cdTg27;i=IuTuni!u+Vk|OT(xG{{lL|1F;U-;qdp^nfhsWq-AM4DJPze zA8!wdis`|D(0wX79_@H4om|?M*x=9b`oe8IN%;f^!%;yojxaI01pBY5+$=+X7Jobf zUV4u*@bIAGTIXfXh=GJnt_f3>O+BgJI49nkZ3TC}&nP67^z@DqoUK0)Z@rvS^3$EQ_Jf??fO$#Xev{hEKv?QMXcOzGnzJ3m{~`l1kEK)Rd#_K*#f z^hjGXP%H0Rug0HV?>c;@#BriNB}Xu~H~#tKd_DI*J!TIuz|EH2jpy$N4NF!?VIg#86 z=IQBGN=))kws(xA1OrI!EA&0Gyq$SSG@&r+urAc=Biq>6zh5Zna$Zy_F+&{sY-kNw z13q6`T)tFum2j@2-S<)pTwGA!gW7gjxg&vj(sAMFfUh;|2|XrrFW#e zo+V>)o8ROMEhcm!CM20snsSUNEV~X`XXH)a`YY$^T#{|gFN&WNe99#cp*t~ztQERr zcxB-$nVAz_M=A<@H?v*!_5G)(m<8oZU;>R%jL(!=YW3BFtcqnKlJw{`pR=lipo3sZ z4TJ;Wu_>c-b9W{us}*6w4JjUFjGWiA$5XRb#*Dk?G`jB>lv#bqQnOiajDnAg%kp^O zPw{NfB1-(y#*jtb{MEN;7=qRs1B=+?6j@SP`4H@l`B=-o{zedziwCpNg063F0DFy8 z7O~Wj%{>3@`_+197v6}7?Y6e!q|0O}{GI$6WB*F9dRLK~B$Wyc;yB4hC#+ve zS`9GqjU!1+43QcYew9oyeOq98PpUfCm&b7W%JY;&O!u1;- z5ty?eAyfuNCCN|`-?_M|tE(kHz7TckyE6PO!s-EIF{zi=B`|)y?n;CPQd-fk3<={D zJ!o}NLiC9}LSQ;CJlUefpE731so@EgnzH4@RdvOnzkYm@X_o}9ROZ{2q9HO75j>I! zy@^s3IrRNRSVqzmGPRRKScpM&OaAnd@H=Mu+)8G*R(s zU#ds1UbS|=WF?c_4M{`HWmMALU$GiJ#=i-6m|^QLp4dOx0FA>_JI z8-qo10Ot%T1T@w4*kY&K+i#bbrfnzR`L*f;qX{i8+zg?h3S2&~PYcn_8L+jTkds`5 z0piRR$G8{)w7KB(CJG7AI07_T{*oPG6nr^U$QDxl>2yK2$MYEHDSTCc%joOfK~k3nC{3KJxf`fn4UilG+BMd@=RqoGo}qH) zrR?>H-s|OH969heh1yfAga#xBf*_^C@Rz28gES)TT$@%=;1@TK3x50|((2K+7EovU z$Am4qLJP{JWpTgG0NzLWa)Wo_@HqpBW7Y?^ zGSl#g28DqHYK;%lrhy>WpPxfXZIkZk>0W}?j|R(!fK%(RAf-M;geqpgxva|jJf#B> z85w)-ulI8viB7HcBEb#m`~(~1)9r~?jbY#W=qWK0z}A7+fJ5pVFm&t{1D>aCJNmP{ zwCeq#-?!LU2mLGupsT9#+n=MIy+w3$^j@e71VIhJvVw>W?-jXDz2W5>;s~q@ zl{QrdqEj|n78&Y&c*uW&HTi><33+&}K5yRE7zUWFS?*p}1d3nPT&jQnUfm}^3^{AO z=vP6|TVh`* zY+XR3r`EDP1GLTBKNs?AJ5oAfSVL%|DGD(qlAdv06A2~EKXh!vq%3jfiE)H{4#qvn zj0%9~c;;dq&R6xbwYs8`rnHx};nLFdX5Q@Otm7+j503`h<-gVX5L2qShyh|CBPWKB zK-O`8g{m(Z5JcoL&EnI3XfB_f~5UZJ)ETiLV)FYs7!5jdE`H z7K~e#l&C-pt+<6BQNSXSm6nYtMlbj{6$3^AjAr%jyK&?fdw^!CSVqYg zM6@xWw*oK>UT-_|I-A*bc6LrLunXT}m23?($%qBmlrbCmLrwjz>j_K#wB3-L3FIAexDdv)sIM9vM}&(exMj3@Un%Hxw=;gS zAQr-bBjnWP2ex3E4#XD5HC|*NRE0JwTTZ*b&kvCc<2pQ@G-PYrXt2>q_>q2g!da80 zNva7QKG*{(2wcX+0Qu7TF3e9#x;%R0K88F5$^8cp0xua|j&=Z+lBY%hmSaLt{xy37 z+D5_iDEmZpDGeQ6_jBAQpaGiTNdpzjo0!GN7-piB$h+&CA0yLk8qi)u6&hNI(Isa( zdB{*+8t&p^>fj(EPc6{S!LBrdhD{S#NsT8=I#+Tr#V5Y&JUtrNYDfwz$f`|1?+wZB z&M%u2Yk8r8=ymrnH#e{2d9ek9(2vi)vjdD&dh2+%3ZXEh#)VF$Wur{|=jY${dowO_ zPInj(L^f1Gm{{0r4PH-Jfb4nsL&4drF_O8RD1)^J^cf4W7Aj}7MhQxmYHHK( zSjyQRch+D5ZFDD))Z67cUxMwCTxD|En)h~7^u}ogMF)GRyYa4dwbVq|n(2oSAXVUj z$Dwj$Kd4_w1KIkbbYVyYaBGU!{x!c0+X0%Tw3M!ws(c>Jy)MzLqB9%K=Kjx+sBVu!NK=Iq=RsNn~Oh1kaVWdHQ*(SLknrHt#){j>k{JLVr1oO zF~!+2z9?~TO=+Z`@2^+gTV_I-<% zp#~yjPa#AY^@w7X4l>t;;+qqZ9C109TjFO3(z0sTeuoH1_9U4mw06XDw~P9@nI{y1 zZ>=@X`^Btpw+$VXZ+oqQhw?i#piDgIz~W52%w47#0tmHp+_4@ZjgmU1kf`&k&PSoD zc_r9@GO$ibaj_7}kv{^HzJk^B9}h_%A6u4ClR;D9{LCAR%vi#&ST0NFIQ9A z;_MK4V&Z|&@)T6fv2TBpae4z1v2yIvDd~c9Qw-S<5rdeQEI(Bnqqii-ta-9`7%Y;s z)(~T1-7jtz-^dMiE)E9tXne`n29D@{VPBj<6rZQ%z%lIe9}R`dRsR;00H<#1wF~4o z>FFdS<_DvGG~LwNRU8!jIJ zNcv{celUT}#{9=^X+n7RmU379V$frA;zm&f(kGEdzRN*!RD#RrtPPh)V(vCTs5V2S zVv9=)_eD)gdo(uDO$hrix^rUd^VzhDfq_MA6Eh5cmdxl6IubD2Z?*h6Zro_37_+i} z?l1rB)YRYgx5>RR+A^$Ue+Qfw#JWT@v~WYR#h5~hs%)gY$sI9-uh(DnsFnP3aeo`9 zHpFtlN{9|`()A>LDclM|2r-1t5>(o}zu{6f8^xEN!cgGz6M~~B@&;|v{ae$aV%?L6 zm6d_^g9F}I;3O^ z>mrN}$M(+(+{r(=wB&HlBEU#vI{yshE2*8|3xnf!1YtH#@a&$A>S%-asN z;1rP|*L{?&=Qi-=t`gYA2^Z5{9_TSU-?~|Uds%;^^SAeeH>=Q;C(a-?bNNlJ&fO%Y z{&)A02`KDS!9ZXYnknDAzyf48vz!N)^M33ceSU`lV#tA$S> z>(w5!Za=UU9BePNFg5FxUv{jJ!L_}Ho6LMxnm%95WAxM>Np8>LQ<$lGrJ)yxktRc7i z=uWG;NP)_zt?eQ?nO?m@WEg*sBMy{fiib?HQr)Ggw#UF!zq@PjX#$4@D?*%?7oRYi z^6OW?c2eRdqIkbtZ9qo%o@(*1kDhgMekTQN9I?S zT1qJ;)S^!1*f%o-=e?bpEJcTI+B3V;2twuv_9b(v`A?sDa~uJ!c?}*iLG*Ne7?fWD zW?=+OF^}Jqs?9I&V_S$mqST`x@r3baXRpsrci--@MwqBOI$B6e+Y5IM&G5{wwYN06 zuhLgRqrg>k`vb1(fs&FE;1jC|0y5tV`Ms#%NpjY> z1vV*t!Wa_4kbo+RYjTsC@&LDU7=;3cFlbnMx60~stf+y6Df7Y(K|FZcT#?vD20iX<#7YSbh}idqZ6 z5Ao^tJHO{bpCuGqY*Ho|ed@FokqBiWDBjl65+V~f!R~8?UNCR$P;CkZ+tjVg-SY#60d2F<3Op-~M!5aeysWbm(tlbWE(kRs)XN-K;Aw@p zp{2Eu>eNpEJEV^A4ML5XgSq*6r=L&rHZtMy<|)b>A!kqh>lAhN^SbkKc$R$TuPdzJ z0*ZhxW4(2lV4`kZ*961=6@U2Oi$5>qiEx>$(34Ny8h=V!KAYAxfyB=oYTzud9!zyS z7>8ABe*Vm^&{E&HU?7CcuC)ikXhy~f>(y{(X6p9fItI!Srt8U1B|`1OTk%~&m_~S; zbj_LQoHc`GkxDA8SXo@@#g^JLZBc}ad0#2}u~zGNqg9Qpl98HVB&?a|JPoB$j0~L% zl7UbMk=)l-2-9|QS~w<=dyB{WP5kC2=KI>e(TRN+NLgueio-KzM_#2OK8Qb7mCZ-y z9#4Dy5@rTD+iQ7kIOb6mY--wh+=cHwWbc^Dc7%TY4A-Y*hSb0JBIN*aktvMiWQ5xDI&y2>zx8 z7kKd|aPFtF_V&WHx?>oTpWoY|5AmZYI#Zia`?_7g<(`&6Cg(pjdIkp~u2^o}jGA0< z1|%e9CsqDCUt^a#!8}2W42_anxLg?1T@G&h;`Y?0p{Hj5eA6TQ$MBxRA`!AlMDCc< zZv!!w52vmvOxoP0 z9tm(aQ^VceI-;V(`2r^2U%X5%D8G1oORv&s`;n>UAPod7(0&$CzQx{Ojt8g%1oJ?@ z9zR9QNl?VY2ieUgz{6rdLD{c_-QEqbX!E!*EUmAvEjlpP0w#ATHvYA`>Y zGMM2~9{f^7gWoP@Z~j)VZGxB{SHZ45c3`IwH(LDbPirt7ikEWnT$>YB+Ng62&iwqk z!_}B%Mg|;OfUB&FyFJ$sU3kShdwBVZ9BS$z==|1g!egx`#cI1h3c9QDq<*>9LAJe{ z*>+{{^aHUz+;E^(S52qJA5V9X_?Z5rW-1Q9DGDKjH3CxPSIzhE94G)nfI`JgVEM$- zy3>R{pj>!-=B-CWRQ0;fJGooWJ~;W}(RSdpS@3b554U?OWMJ=tqE(j(?La6<2oDQJ zd_=kSGIkSD6B|{<(3E$>IkZyTgJEIRR6^)`@0Zo}m(?LJ zBxGb@Ru<-&&l`7Fb_zw3- z>Y~~OHXlnAKz*=9k^Dq_;UMi4fmo&P#wW7`Lx~!6BzT(Hp5Zqv>#B3@=SFyYtb6&H zJMCBM;7&@4kV?uUuZ1TB1Q5mWt9cGl)@NpR{^X}3|KMLpqp6$27W+{Y3GwHz%gJE0 z%3L}t%bYK_QDC}Q?62#CWmFOp_E>osY(1CQd5nGGY3JEFTLnMZFQt@bqc|)KOcJFM zad7tarHpco5Pn?sUgeS{w~ykS6;CG3Kvy}@1A=HCn$R)2M-rfV)qLt4*#``jiM?(D zpDD}Kh}<5-j3zjOktdq1zyHgP7>4wlwe_Cy`nS-`?DMdMK{rzJzb`8h#2=5(tNY+> zAQC|H#6FJUhq8g!iNgXMR1SZka@Z=Efx)jz!6=FQ<#!o zgRF0Dzlf-r=TK z_EA_ByRKfhki%I$g*yteAv<{m{bF7=YDGx)qApPp-so|5;$?C?JGDR;HFfJ{zQ@Qa4Zp77vDfezb zbKD}PzTFsV^A@b76w;?>#?G%ITlwVNVnwuF4bw*;z)SQSbW4~3KJz%*b`a!#KTSp` z$$@1I2o4c_yguG9$&61QVeL2;!dh_-Pusmba+OG&Ok|M0!oL3sfPCJ8C9MI)AE~6E zY9M$&?#ahW`HWi}8}eH}4^kcI{=rs<3-Aqw#oAz$A_lVu+SV;u+XWktW5lv(K#X{) z+uJub@vw4hw7M|jY2%Wl9*P`X6Z*fW} zM+O;lOu5c8i0?|meU->&DlaK1D;~W4^?5_JeE$M z3NrF1&cgU1-wwM|RpR={FaMo(Tz`9q^(A0%QkGDeUo9k6ggXej9!8LW9B znH$Im%_4k!aqoU31aLjC7Vl^=Dy6L|;}=02$69hj!4fSR$WCm3m0k&aDfY z4lN1gq$mzg%h=5A#2#)UwZ&;Z<5{Iu|Cla`XcAhYg5844U?hI5;E@Drpn?~dE!fcf z!&E>#EeXsrgQn3~{hF*b9wX-eber6MZD_cU>|qX8``z7?Q`S~gWm`C*yZ26u?PCK) zPM(IJ4WllE&|repLSS?yns|O~E&8r)xgu(XBAZz>n^NB(@ePZd4xDRjc6NvBx`1kj zs=nlyGUDE^)Q^U!p%Cz@ha9~6hi-h;w%KFHe|WQQ{UNn2l>-(l=$wIsDJUL@3|Fd7kP}*o9{t6>& zcf8NYL`=uvdEJLoboJZ#-+y6ZD>4ucw<06+pg{|50P+HJ;g!a;QJvp_Zo%IIYlZ1S zjcWN#%t}aG3mXgjrd7B;EX-ZSB#tgzXH^lDP#Lx%aY_;Cf^+0@F?w&o!ds0^tHsb} z8Gnn7B`W~iOZ#JtU?D&z!s9I|`a8a@iY_F1viH7tc{6F@7fm&$)BK*g>a3b7YM}1A zV)XlUe?i;Wz2YKyI6(1!vFfc)J|*TuS@LXeU0ND&IpwR$$#IHYxSesTWwQoe5x3bp zT{$lBBkkS|#KFOlX@|Gw(1XOa;&r!LjfpGk?EFb`RJ|NoGMO6DEHc>+7PAwRX9^Oj z5nh`bU3$rSxC&cXJ=9VGW&!CM%3rv@xC*lyu{4h@G15Vy{AjX5?S&2h=yP|RDhAy# z703>V4HDcux$R`QBd1f=E&GCBpLa*1Ab?N^K$*B8BXAhM@!PJ^fB%jhBI;$$iJ(RM z=Z`D@<3WnxIm910vi}pMMgwA&#p?%?doxtO+S=L)pk6EHO<@Ni5?0wRaJAXfbH`O2 zv;_xiFxgL$?q}D_&pJwR==2SVDJQ*CS8-;V)~ejlE@_^T2{8{-+z@DejjUTmo>y() zC|TQ}mT2hNBqF7gaFdK4QY@Z4uBa+~+^A?c8VAHi5G4BtzqdO-lz;a}>UpgZk*Rga z8DmK)^E2xmr@JXtI(4S7a*BoTWdA-lkl>DA2!2R=%?|OMKL)(QNx$oVd}wO2DPo5e zon#0SVI)wp?gOowC)SM}mQ+SNJC~@1i49vuxwxQXPM^9IEkFl_<4S*;dchA2RB8Sy z@o;T1ODd{dizE6`ZvLxy@Uxf_CZf_{kAf57BU)~Jc;B#tBhFab)u~mLGuc}l#rx&L zKxC}GHpTpZJiTLh7+u>o8rxQ5+f8G;v29xo8{4*RH@2;&jg7{(zRCT(d;jZ?9LaQM zt&1moU-jP)eG>@fy#ZJE2nH&umWtzapO@*{T43Oqew}4X7|`1m3A|S4hvkXMO;Rwq zQgj(iQ*)!Dxjj*3Y%xwr6y(Z9K;rx4ND2W_lP|}G%jSFWA7DXVqfo|^J{h5aLFI3c zqlEEYF=+$4%fyr>gfX-`-iY$Hw)&7mjD=n)WQfKg*_{_R9OL=zQRjW>WkWqFS3fSd zHk4N4GgPp^{8mxtNs#&_Y(N9+BK-x4?%vhZ^atPTWvak+JTBY!^e`ZCW@UcDg1+W< zOnRcB^n&Bq2(=+o;)0>LvR_9C_cFGMLfS}kHEXT!@56kpO54T8d;&}WR#)lxawOUD zLVvdEz%I_mjp2M(f$(IlFdiUc`Bvd*M9x^uA?6QEVEoIXypwd{p4>Z&^787MZgo@j z^;Grrv~;RGQ~!ILNd64kElBCIf4ccA|613tvMBexPo<~+b-K0KjVHU~;9#>GW+nN& zR-wQ`(+P>sCjFS46y!xgNQFMdkToB(g}s(pSa<7S?f&0$V)#37MbQtb>wdAb9lA<&wSbA_0{goEck#_~BE_T8 z-26_)oEn6c;q%3heeR~l3&xcGkBA>+&JL9E)d2Dj5B{@0 zDdgs zH;|AoM*=}i`|aB|=}H-7X>?d}s^zFYrI-mp@gUj?FnS6U>Y6g*PQDG%HvqC!Z_pRO zFe6ag8d|_LfFb6}Kc8>Lq(G(`I;~u;6I+Thf!^agl|Vre9LyhEO8oU}w(Q0S;A+Zl zt@gOpw{~#QdozQ*>7u+mU+mFn_MPO>1Te24W|o4X*K8^qJ&Hm?;&yT#u(gFqRQ=^J zi%H70zsK9-d{~{T{~prfd0bu^H~IVTU%++RotN;n5itDe0Z0$~`}>{FfEJIgmezAf zwj?C*YEU33zkKe)kjh=$<%k6}Fgb~zVE^WXab)BC`8|(enxrE}r(X_2J&Ul#61Dq< z5!=Sx!6EKV=JdMW#j#I{nTh1ciq^a=8W)$GDvn@}nKRPVLqxSi zivkbuK>c{zP}gU`!^^Pe#HK1VIUR|&F~Te zWh&qrrnUPqKMU==w`a4|eA2#Hxr~AfotBc40$^miPINCSSP--by-w=^vq;yIKe`Tm zkO0nLhoQye<^a%TeIvv#C2IS;SOL97pDpY>Nixz5CIrS;=CGiQx;_eGH1g|#bX0rY z0d)xzdWA>}^7+53nY#~#8GYO!wIk3-1cIQljq$s*dM*-`vXrrD3mzVTMR}^ega3e4 zwyI8+SH-{U)fSs0d#h_`Fi5k;1ruSVU6yp=?aMzzuf#1iF=dN~?eH2DZ5WRTM-rm@S=mTpYpS4B;`tB8A4h?Q)IkG(GW=$KXDl0NnRf6`4+M8S^ zQW*Z_jm#gB_H4SKDdsD3q5R`@vGAW7#?Ev|sFxkK=1gRAX#?}|5mqsK)-RsCSQE=L z`cqZ=u^?dUdB02rya*TwdO~?xJXP^~3W`i5LLILSkMRts z3U)rg*xz@3xb1APR3^s|mO@xf19T2*HR=NzCg333pL_KH;_jS zSv8~fP-J6$2o$0wb`mouq8MzNOeL#7k57EOb-xfiJsoKv$nU$QR?-n(;N$iC*;b9E zU|?r*lDL^=4Acrs|K z0aOEgw9sCwgu)>jt+;}(Of+BRIQ$ho2JY%g=z>&X(V6Ct5H#r(FyM7430vB9W-~P- zu~f0JJLqTuqwJArZ31q06u#?Vc0dcRMxT>My!YoR@$`-9zCL%{2-_%qkHWU9ox$nm)Stb$@qre4k z<09T#3sY^)bV};iq%rsFo1+MqaW$pS!V4Iqe`4p-`!vs4!BGVR{7Xd5f3)n-k`Y~x zgRWHp*ZHBBb38TsUSLR?eI7p2Vazfy ztI*WEXxD7C9fA21tz1TP8J0fyJ+5q0vz^`Lq*^=Iy`ZZSe&Kbzz1?FXRsXgRxj;@F z@?IjJ+t${WIuEd7i|v}neKatU2I{8hUJiAgt1hn#S8U93uDUUD5;e|?P2aig0Yq0< zDv&_S@pki^vFeI|8Lo(k2!U6_(~CJ=5$Dq(pO+1ft0Ai2smlNRV$7dkjCsqcBRx=1 z(U8OlQTfNi6^&(t5i{ZdP$`BMv`#og0kSe0=$LR);Nh3(l} z6#4Ld%;4a3D%FYBT3K3pazPmBg>=G2S;luM6JPGycOe9Ozs>O2w{90B;;%8PTbh~< z1VFCA1&C$^0rC%9p-nY4NV-U}X4Y0#gNZX&BUImn48(~Q)OBs;ikArLjh;d-m|{m( zXDtKH>`$eAM$VNLeUo ztgPrr$g5l5(NUi1;wn2N9jT*qH!hVB=0MqE)!cB+M=oHii;3QD4BoY0ZeoA%#;0Vkf z6ck6y+M4cnAR-JY+qsQR)06j7x6rrQT~_>j#mgnfNu#IS!`vB1ZXYa}w!fK&E^4(J zSEavxP4@{sBGl5WrvCs~bw}rVI+{l%3ZGdG2Fx52C`HUMf3`ijh=Um4?(_>&ock&E zk~U#RZ2M@$qf18{tHl)*k)}u0Rz;0MH8OP|Ji#7sNyizXpw*ZP3{VVHFqn}T`LM<@ zA0`j#Y`e_EG_eXB+nC)9-@8p7|0Uw{Jc+LD*yye(e!6!J-yJ9*V2sNVxeff&8jxVJ zybCbO&7B6r-AV_Wz#vxFID~#nc5rQ8l{pSfPvS^a${AD<`R*EG8G|?G{QY~e+DS>5 zm%Yd8Dx4k>YQnRam{<$2%QBATUtwi;Q4|wP5R+mppR{^;PD|2DQnrOE)&F?@`*Df< z;U^f*wYEE0M`kr8@Npv`a62o)$H(`m#B$}W}vEksRuds`40ZeRaAIH7u zK0*j>DoJ%tf%n$hc06Ttcu)OjnT?H~3#O^rPBDi-;gQ$fUD?sm(bB?%^7u9z=X<`U z{3q#?N(LN>|35@qMuFHh0LFxx>ww{B1Ktua9u@KNaa2Sl^i5x6)@6xWSxy$s+LkT8 zJ~=)G7?l+jvsJ{LyvK$pQM*-UqO=8YW3ezw7_cmIiUa>V?bMr?s901?eqm{@A8c(0 zwa{9+rems;9EDU|)iHV^P{hv?! z)-`Qr7aLs#cwdd*3C$)&XID)k{rNB?Ip#4XA3HYR&Nuq{UI5XS?99lGRL`?5!nz`p ztNCK%DLkLKjAJYQcnkLXd6~%T>!nE4$maU31SjA%aT&vuJ*1KY|8f_BKq)e)iD2QD zQ8k)J4-&1_l#!8cFhUf=Cx&(FK%`rgJs{h@)USDtST12&_MDTG0TrO)vzxbX&e#Z&qRfNb{u1HcgtjC!$s$f z!g;axayn`BH(!y%DufpNLTxczC`E zx2grJA$xxgnBqZpdQ-XYD#_{)4P8$7wwRVk6d}TK0Xdy`zVMpOw0qYB{}cIqf;D58 zN^+WPW{aKA>C@qtp`n_9026k+Sn>6tq4brN$ipe^W~bsBHnA8$i4UY8s@8j-?h{pv zVyg3F-Sx+s?gk$nNI`|O!$O#oYg zxx32B$`PUv9ZU$y01)3$@^|`rmWe-98PW^yZ-klOyC~d=G^*boVY39a+N?0M%&&Ha zBvmAh@;E>zivVdBm@LN6h|XwIyqO*fB7_Fu)}h3NX!`TOEsIdvJUqVXUG&bztsmVc zrFxBzUlO18$`<$ZFvm-J@Zt{GZG<3&3>6esm{KE$qWgpB^v5hl3(GOG5qMV;CPi5wd zUUc5h=jZ32@wf>lQa5oCyk9$s@6?pDd?SD`OShUiiI*Vs2j>Muhz+KfE>+yX6ouA5 z#jSB)FN5L>SMST^eIg+L!0vytf8?msw`i(D3>7@~VNwhC0QJ-D=erX{Dzezxpii2_ z=ixS_=MIY|#e&wqgV;O?(qoYHkah19@}=kBPu(8?)cq5^v@ zQiPkqez%auZ@0i9O);eOg`;AwSrQ8#)T)0t8s)iOw^(Kwj#B&=8!1sg#}qInE*t}> zt-s@BcpuiB%Op|VP2OLhPMaJ3#G!4daa<1euj(Pd?(gr{_`I?RXT&>vEJlzzW>PZ* zi2Nm?pz|INSku9vk%)EuX_uDX5unh0e99YG)eT8HNim}#?lYAgWr`N@E~@J^9!lm( z)Q%|8y`Iv#dR3t&OMbRS?~rrHFCdr)Wl@6}OS;dB1m2KO9;|==P5}vd$e<+})`G#< zQ>BL2mvNoKKsF2(XlZ2$JDGh#G*Ek`>0MKo^zj(`0dNcO^t}@$1{9g3j~a$6&}X7TwNm`6xeYczPz9I|aL=4TFPTSKVY-_UU+NAjr+6JeVXE0@=d zANDE8Kr2`4CcbJ!XobbGTxS$hANS*l`6i47R#!iL`v!kFEruofTXHE9mj}yD+m`e9 zA{sb2#n2E^7QKAe?Sn5My88Clcd8ZSHE1sXB!K%54F#=zcCiB!btu+B92Ev-?0XQX zL1|DQUy`bNNEvg^oNHXJ_vJGC)He zow`C39SZuF`~V_1$&g~f%OC&#<6>jV8ZjSESZ2fNADvNQY{rS`iu9NNomg!D@>cfr zHC$=?fL?M^zk1LKLpe$(Fd2Ro1Nwr?$)UGVTAGfYsEw~;Xk&#Kx z(4h>+Jx{Wcl=LbR{dL32g{WGVDWw>qd}{g)%?z9!j2Q39quYtqUw6oe!A{N$fq`ps zsQ4I5#Ee+*jQu-5d(Oyp%TFO@j1CSm?FkRhVVZ~Ap0Swnvx9ME@W40_T&^^U%lfCRLu=Rzo02Rha4+mn3hor*q^^JJG__Wj;O0))PFl9A=eEHrC0pqt@xE>78|}{u z=~6Qne-h(7CKAA-7gNLtqS}jAmSG+H=_{ld|0M$xM%0)k4J}YKo-aq*(CkV}c_Cq3 zIu$(e?I?cfpV*R9gJ^IaRT%4r=aO`5XbBNupvMsf6FRii7fVT7XxPtec6&7D@oq*; zyX?fGFfB}yE+w(GsQv@6ygaG?W4hrI>4|CC^Cca@w^+Nyw!>m7UFY~GNA^Yr}S{f;Jdo8A{ zOQ~F6V%QxC5rqThu`|@A|Di_H3K&RoCPR3F`B0AR~Jkr^!Ubda@Ba(1TuHrIv5nump<4XfMa`z z;Sbw_9>ao%J0{Nofl~T@tRAaPe~0B)vm+#b-dJqNepPufc}~g2v?NIGDk;i;&~Bg4`Px1+ATW+X&0C~Nf77llLu~* z#elY@B0*!E3Vn&UFJz!pzZiZ1l1o<}%0DAbc=+UyVVF&vY;_JqXAM`?<(8%Fp(nEu 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 Pf#1D9)NkkCGI{+U8B#P2 literal 0 HcmV?d00001 diff --git a/notebooks/tutorials/hist.png b/notebooks/tutorials/hist.png new file mode 100644 index 0000000000000000000000000000000000000000..5b0b0682dfcce4b8f536063eb504de02f6d55aa8 GIT binary patch literal 11038 zcmeHtXH-<_w(SN~6hu%I2~AKi(i9>fIjDe=bC4*aA~_d1XqyF56p;*qWC@Zfpp2lB zV?hxLC5HkLD4>e)*6!|eU%&Bg-_z&x9e2DRkAZ+ywfFwQnrqED*LP1(=NtiN0p;$3?BJ=wxP-@bqIXtusgsnLh2*F)qi%YbX% zl@qq{Gg$WYb2-8o5hvA7Rrjstrfi>>c5MGf&tsyJa`6{6ZLQo#$~V78*>6sKetO`^ zqlU({t7HE7=2)+><+Y^M_1Z}MYAkDu&_YGHm>P_&Q0+)2GyGP*wi}^Cke|;YTj0f= zbZiLn=HwP-c&CBw|G)8fmc%LnBM>DiAu-V)iZ==hsFPC?x$Agwl{|~pG^>*3YIV( z&!VGW`VRWn<4BxoH*V0s%*Z%?>Xb=uZ!ZxaivMLFjP|A)Tu@RXA!1gjjPsrAo*lqN zKY5bIzw!Of;G=T)uV+NeOU^&oFWQ}Ng?pNikmoU6Hwm-fWx5MN*eo%2;T~0Y^(K3Z zGecGzY^JU=^65D`=3H%xdnw~Jc0Nj;FET1BYH_hcclz-;K8LRPsi~>Xv~#Ro-QC9z z960d&B?A(Md>!}Q+k#k6tgSAXS9-pjnx2k^Vc);cWNd0GEG0$gt0!Zf8lQ_1i|o!7 z*U$UO=j7%t_(O!N#9?&yvuV*NWJ42^XFAD>uVC~}WMV1z$;)@8Mh+c1w7RIPq0ye1 z973F#zyIKYv6&fXXB-_unUeBNBvI0sU0FR2-NouFF!(KXnL5o4)(|VbGWh~$#I$2i zs`7`f75U;DMt@AYg*&ukQ~ejlvdhZ4X<2!BJI%@P{I`3$#KQ)vd<-`?)(@$_zr#v^ zMOy6lYVi-9E2ye6KX&Zc;D)56r1sUVq9a(`C>HmNg#G@hiL!+A3oFJ3-`t`{OZpklinIHykh&tLM$w5EVM@L7q-AJ{v9^Y=7GSJt5ylp3E3LV3?tgNi_9v&W5%Y%W57+wSs$a--K34w{l$@{;~$;m+% z-YSq>N-VVfr7nW!h`RA^jLDuNJ8l`z^iwXx^pzFAJHm_zvK^CK%Xp%7 zh3^2OEHH2SCiQKLTSEvVWEkYv1T+2reuB~3pUJGuwr{cG8m>E57M9-3cH4hLhJ0`S z26-`f{q!&EWvq&R0w1CgWxtDm>BcH9$j=x|_ubusd-?ebK73Fa@E=c<^`3a7o1AT! z`DN5|Ro=DY>$W?`p_Xlr$YKe*a^*^#VsI69wm&;6YEPn^uTEuUWlllC@}%$dt8&=Y zFElfJNX^;bu^h5{@iq%jP+5$KMF!lR+*^E3YQXzR`2ZO!EF&Y+ISO$leHh|O)WpI< zSbYkBs~hOxkiCbUUDAC>Sz+z_`<(1-j~DWgsUF=Ua=l^ZvU{4GT)^X2t$+5;uBEc^ z(NTwQAMR=B>YA#m-WqF3E=WlD34M%fIqtIu;2pkwaryZep(V&JTcY;Sxz~krQNO=u zT^bCWTP@LzllV*vnrKbsRt&0W@8~FX9gx+2ej@d=$M5)D3~2Lc(W**Q?;Fk?#HQ>) zkaxPBp3q(VJH>sAq2DkI+>63;}w2U#WOl9cNR5 zjG+@D-xy|i^5jX(YFq(+!yK}UhPwJZjzq@N)~|5_P@+`GJBJo0JC-18I()pp?|x*Y zsgF-76TbMnrT0F3%dVK%lPNB}Rt9W)1QGlaj7alRTk(bl={+CD{u7i}AR8^}e>P z<#KxJhOrIe>t%ECuSL=LT>NYC`9A?^Z;vWui`nT&P3&jOq{-qMw=cC9jTw-_4*;n6 z5*9_jH`g^CB1TnjfY)6obT=W7Ek5|wli99>-FT7#K%z0PuvjxTaweC{S+}4_1 zJT>1ZuHwlZp^5C@G~P9gdzF_~D7n0yU^8y_Xd1BD?WJ3K$!Z0^n9JhIyWQe1jUg6L z`tjpOZm~-@zYPyZKYyMjH&<3J%u;>8;V}R0BeB#eChEx(N!NbqL}`zA zZ@-|0LD&($J>dOq7RA1XXCj7|F1?`4^rpqTR;kx8B-nrtRHlBZ;bXe2U2E^spn*6=|Qx6dU@3Z_q&z@T+?{vu+j#C z5QaxlWZViD`_j@vh>#l0N=}){lB-r=$o_LssEtDO>eva%k*-kNh(@9CqAf;=Jy4 zvGrmy`7I-B3AOZbMYTnRpYMXPHqo_t^}}@y%)32q2j&~o<<`oSYNyC4Nd#PVD!&7> z8skzw@9wf?&AkpSEjJ#nttq>UG5jsm{f1Lpk)iGFZnLs;3&68{3-^?m3|HlRt-kH( zg$cq-eha?y@c7ZA*9_%uhFkSM{1lv@>hZtfBPmqGpxgN%)gOsvcgYZIrZrk*}| z!cM&btMx*wXX_gvONkIS>a@v@%u<)WQ;f$Ut=z@f7Vqu9!yhscyfI(TpIcQ$#077x z`J=Qd#wMha{UxAGCAx4&7>PExJmOgi-)kYAJb>cyEd&- zbx4!K74%(Mxq08Db-4ess4ml>&&V3&9jbG^^V++|vaQwjhX;0-*vZ4f@8Xv;G83#| zU<#17qC2S9v*is?T`oKC(P-1D(2eoX&P-kYxmwqOs$*he`j8y3g=Zj?C)iHWolsD) zit21_9dbVe(`yrPrXRWmJY6ZPq{IlNne<y|?3#mATE0xqz9X`c9m$ z+o2;z8b&?+mn$tXXf{=5yk&)~eH0Bz4PA{1ZA*~xO2BM|06czcU>V_)!)mb~(ebW= z@)VY}4@>6`C7)R0@TB7kJXqybA#Hm_=;lV8QfMtoOd1=te8|Ku`%T?Ys^OjE0H3?N zZ1*EE7^@s0UnciaRL|UZx+KR{M$cXf>3$h3cQh_BC54*6iu*98miOaA4q4AGs zSXKzz@Sf^aSEBW{Eauv*f0+bV0Xb-`vPD^)I`Txu0;X+dU+t7E+m- zv9YmvxocvER_r%DV|cSoaEAV(zkg*5Hd7}N-A09lM)8<6W?OjA(j0s&|BcJuV$+kbmlgI0XnY!7*#Cb0wxX%%k^jh*79a9%r#HTA4# zr6sqtdkPiUN(KSGoO%jvt2Q@iOT+w|J#NVsZZ*bG6Bb;3r@LRBm4wSxZouVBOG|Np z0&D-#eV}O1N6Grm=HWMKc)~)9Qb9#Ug$eHwQBhrge}55*2W~(^M`zZ(2?qUGXl8>+ zT1m+U_K#YyNfqT)3bCw@*E{?s+S=L=))n|7 zLF)xU_Cg*Xp1F#c7FfTMA_W73p`rM#acBU%;>_{Ormp9Gg4(&p73sCYLSH6D*#!IO3nMUg>z93f0 zEvbdj+1b^F3NyOg9e|v@?`8#u^74LOUmI5DM(rfByS#8n!T=E{M`=9~~2u2|ApG=ad#ym%!!O=st3HhITw$`oBr*4x$V! z=)2PpO8`3HzGekAl(=1d@<;8$XDi3~27F1u_ah=)mOONla0p@ zg}O9N(VBFn^-0}0aeJNIhsA-*t`WR)-ME1jT%ciwR$J5|&5}PQxYv0ggD7({K`x3X zt*Hr{GGz63qls<@E;5WiVB$bioTR3GOOmmU&O@O|Scopj z0t~f#ppu0}z}3x33KpcGg$P*E3~~GB^HG;BU6QbG{;4Tms^#kxJo}(c&sOD_hL_+L zm@kaC5FniQLc#}OErFBgfe#Q51H98vi{ZoF-8wPX1^m9YHIW0XEV_TN*r&NUZpPsi zo#LxZ7*paVyyuDU+)5Ut<3+3%q}ZS+lsnj6PcGZu(I0?UPTzr3qK68j?Ed$>JFTAl zt>Mp>;&GUx^$I7hx$8abvnE?faT+w%i6&qUqz@id9QWSg5`fp)^wD7xJ}teYd$ZvB z!@sEn3itlhswP@jJ?*`tn`zP0?Q7ZMfg9tBgekmy?`uMvY?%AoodU4v{{~(EjX3;H z@Jqwe^q|VROylJ{XloJ5``OF~iH+qs-CyxTL3x$C4xnOASW?m$aEGT2%mq<+?2PpEQaU@0KGxM8my@%g zEzkL8n8BRb?h_F+8=C^#_qS1U9SC#`(dp|LLxS`mO!J;i!R;b^B;Mv_Y5p;HUoV* zhMuTDxL;#foaEI;PI6Dt`?p^p41cwSEDWryMAX4H`r+^&4%hS_)VK6jsEAu0N7EHP z1_P`2RGowaPS3-mh>4l`7b^~gxf*0prl#`ViBHu2!uV)@x+6!9Xi}%OE~drB#T_ob zu|EznoTHOdP2`s^UsAduzp?E!+4d$pd?!pXH$DABA9k#f3rc`PXO@0bZ8O*l2M)X) zhoEM2ctH^ydU8Z}>eFMvK{8B)Jb*KW)YG}o)H3x#@zrdwsTj8HYz?DhFfuYquc(k7 z0DZ8_1XM3u5Nrsj>Q_LG1IiZ`77nSSDF)otyxwB_>CS9Jv~WMm zW4*36Um4a_BtyG}SBxz5(K&LZalUsWX!g{do9n-wcHJCThOe~&7gF=6O^ zE>B7!8&(xh54@|Nh`08sy7}Fp^}YSVweYh(0^k0-xcJdWu^zWN4yim<=khuePGJqBgy0RHY&S8fc6;3v=LFV8oJwX(9x z`hwz{(~04twRO_6|JAD*Q0Kk7j7=SY!hu{~rp5iHb8qK-2n$SGN$5BvaQ@P%kgwi5 zDsFbvbI4fH(;t1b+~4**kO7;g{LNm?yO=6C#2h>>N79G8?c!JLcTWDJv1NM;=6c;0 z1o=lm`mUd(Q^1RoLf!EOGWJg4ahSy$n8o*dN0RiwTL2=p_?D4>A|E#k$>LX*>J1Gn zC~DJjGz@#BCne*5*XH=%l3C-#_JoSb`hhaR@Gve)pRh<*bVQ zNmjKZ+t8hhdl19)rLp2$R6&soS2DyIeL(eoyFr$T`FB=MF=>uXfvj)YCzkz7DqBir zQ|cd#T;b^REFe-A=zlX>?);g${cA1|m_4?Wi$$sj6!@n%ZnJg^l@fk~)7_8U1J{KA zQh5Ed23p?MpPHEhCa#5dsBW>zBCNYaUd-1INOtmxr-ITucs}|Kw(QkC@=bT^J90n$ z#3|8ZANc((!!F}J>wm2v{b}d!=dFx4^(L$+0adQ4<_HmJJG@1vfNS zym(*lm$qVw96v2&_m_<5-;6%HU}UX4lqPlM^5vt4533PuLTk!g`o_G~e~l9##In>e z8g1sFB@0Rzw?aV4j~_o4d+n2Dthj-|w3_iE`$f#t8To_sSQQo@ZDZxjvri5-38qoH zfEXrVAgK#n%d=vdZHyHs7TZUTH78DYB*n+)g2S{D9Ptm=sJmMu3gp5K!}NLy-1J)Z zLQK%==Y^Qr4!+FhPR2#Qq+)vp&jj`)3Srd4-@M<(hSWN1XOs2T=k;*?_n^M7cAb@R zp>9?hPJ@BGyYrUGFSkqu^WI(dIyczB>yb?p=plM0Z~bQN*yS(lj`tZ+bW#_XJ)JpQ zT*lPhLZ}<&W>0Y1yTh`sy)ATgG^T3pM?)!4OtcZxXALE4v>|31q?fj}A+Q1vB6`oD z9^OcQ{n`L*D4m$E+nwwY9?;dvE_PZ^%G4IdnhZf9`r=YkPos=8U}>sr#_6CwfRIWd z=YIL3aY#r=+DfOj=cLZ(q$1)Ue%^jB9U+GHdB8K|l?jzDJcUqZ2Q0t^Fad{7H&9zU z0{UrdwROK@o>mgPj3cp_+d_r%ynFLcpT?O#jz6L?!yk z?pN{o_>BM%Ix8hH@FPeF2s)cfULxJo^tH7h?IigN(8n@`cG@#g?=6Zntw=>`RtM^b zY>DWib8k;qr&6a2mUK54b)ost4$D#+vK|1+M$RfO4cxJ@x2^aXiG+9W{cnhC0f>p>?M znjJpliM~{;vhSBb*;Z{(r}we5rwJES8{jvV3gQ=clsgfVit;ZMs}0vh7$z$QKYjEl z1*Dxze??oSZiN+r5-x5q*Fg!F+%wnpk8W#7n+Gi0AoO!MY}oHDXLVAF)V?WjzuF$A zpI=*R4R&n@u*AN_D(ItRqkS9B6BomLNwhh9f%=of4nIadQ$dm|p<4hdu3T|t=ojS} zlA{anxL1q9xOgqZ4JzV5CNECLJbE&YUJDd7QdmLMu_Qi}(;IDI%iH%<*$8sGw3%f}qkT?kKILQszi=<)P_= zX$F1u-1nBRb)GD|EmRC{3kS`)_w~o~C+i>bI+eA6DsyqISu#m3<6j$M90L)!Lphq4 z5a(g-3|-s0QP0@4bCCgk&qOS)1}skO?)gTamyuC-{v>Qt6D1b9m0S|n9_jW8M#^78 zyJU0N3L8T^b19S1+dH`~0ky5^`x;_pA>MqgLN~&JBpJ~exb(UKBQ9FI@`4oH<{5d) z(IIa`g{Z(S@|^Cb4Z+Gc5&ALS3r$i^;F&1W217T4Vcn=D>qCr6tw1x+T)3pXPASKC ziIn%Zk7&Np1yKz>r!0_`wOu=n z+>8XbK*XxbDA%;0J5JKc8_3A?SiD;|>{LxK*zbVfk%g-CbRlSw->K>k%K|7u*CFi= zU%;o#;MSDW0g%U_Tjn;oM6fZ{(h9HLT%SX|hh4@~4V-C!^Z~!&2yR*LYsKqvIBOtG z9m$((<1p?9Nf)x2D5X)nB@4!e24cBLLV=T0Jr~QeLtwsx&_FKQZ(p7rfOhs0m~4)} z_uEOek3%BMuH@~1P!cGSBP~aFPtQP3kz2Cvx!i2U`*41xLEJ#8lWFm#k4(vmsA~a6 z6R(Jv08zI2#fyU-xu&AS^M2+tzF@4W_l-guL-mr|k zxC$;-FPvgn1#1?4R3#Xo+F&;~0uN#9EGii(s^=4jvUdWInt`U;6)^W|f-!v4{F^K1 z*!S1RqWN*u}D9``wvALkM*YoyXH8_21}2R`!XOdp_iz57>>)#^b`qx5_E{g zi)oxhtzgQ$R5x@%yas#-vCvhB4OyqgLd}wp!B$wIlZC;E)Ut-}z@wR7Z7P^Jxa^ib zkPGg5n7Xd+a<>=c$3TY1|Hqsx>p0n0{8fP^-W2}zM99B-<}AzyJ?#P*bb^gPtwewW z5zwNGOG#!#h&Pb!Z)9Qljlm5@^A_W}CF;ikaJyPt*%rO%l%2pgQ+Ww4o&;`gbv&7H zmQ`VIl&mX$9SiB$5o-1U8GfW>8y%an(WmC-Zs`A^XBfceM9rBH+B(R@f`>oJyy$bo z5Aq&qcJw!zId8d%{ry8iaM3MZ~y*G+-#L5 z`03`gL6y{{>C6TUP76lTxwv(DcKEU=rn_mR(VgpAorC| zOW{`|NQx-GfhdoD^r-bR$xv6}<&h-6GvN86FD^YvUPHUV3$vRLwM$^T7of+YPC56a zz&65JiPO`B0s=gGX)3qCakBko0Blh3LmKe-a$=c_#YIMDgtztMBt0Uahvt-9%=^oF z#-aR!?p?yofja!&ypw~2V=B%mzYX9dajjKAy&e1&u;TYv`E(garK3|UsHNuAQm2G{ z<_4|K-rk9_g3>Du9NKVxBd{MF8O!8gN-Q@wcV{;H=Ipj1`3>DI0**WR71yGI(KAI5 z(|B5b4aIzJ0TPzF0WjBc5e%l8XF~{%MX9e-m(Us#OvD652!YF%16-LeGSi2FE=)iW zp})&bT5a~l^k#w?B#WJSP6`HyE-Cs}T1Jg55ODiv-DZXh$lvfQ>rfTL5W(F3SE#oAjgkbGSRVx8P`4J&81QUpc$`pdAz^O zB_2B8XR(S%#a=Loau=t%G{K!~4PC1by*UzO6EuGdJJXX2G)+lpoFS~+JytJd7d>Ko z5zg>cjXtyR9{IHUV|_j2lI7-i*3A?m(Hsi5MAkT6SQ!|tVLm6t#Y^EB9j`)w#KgFU smR6?{fSYk$9%<$H{dmE@>#nRR`M;8&Uz0~{jisyZt9XD;6OU-YV4E&u=k literal 0 HcmV?d00001 diff --git a/notebooks/tutorials/pmf.png b/notebooks/tutorials/pmf.png new file mode 100644 index 0000000000000000000000000000000000000000..998708a5e622c809f9bf9fdfde3bd66047e9b27e GIT binary patch literal 20552 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 literal 0 HcmV?d00001 diff --git a/notebooks/tutorials/umbrella_sampling.ipynb b/notebooks/tutorials/umbrella_sampling.ipynb new file mode 100644 index 0000000..e5e9ec8 --- /dev/null +++ b/notebooks/tutorials/umbrella_sampling.ipynb @@ -0,0 +1,445 @@ +{ + "cells": [ + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Umbrella Sampling\n", + " \n", + " \n", + "## Introduction\n", + " \n", + "Umbrella sampling is a technique used in molecular dynamics simulations to improve sampling in systems containing high barriers in the free energy landscape. With plain MD simulations the system can remain trapped in free energy minima whereas umbrella sampling adds extra biasing potentials to drive the system in the direction of a chosen collective variable (CV). This enables the calculation of free energy profiles much more efficiently than is possible with regular MD alone.\n", + " \n", + "## Theory\n", + "This section explains more of the details behind umbrella sampling. Refer to [[1](#References), [2](#References)] for full information. The text in this section is from [[3](#References)].\n", + " \n", + "The free energy of a system in the canonical ensemble is\n", + " \n", + "$F=-k_B T \\text{log}(Z),$\n", + " \n", + "where $Z$ is the canonical partition function. For all but the smallest systems $Z$ is computationally intractable to calculate. However, often the most interesting information about a molecular system is given by the differences in the free energy across system states. A Collective Variable (CV; also called a reaction coordinate) can be defined which is a continuous variable that distinguishes different states. The simplest types of CVs are geometric distances (e.g. the distance between two molecules) but there are many other possibilities. The CV $x$ is a function of the atomic coordinates, $x(r)$, and multiple different realizations of $r$ can map to the same $x$. The probability distribution of the system can be written in terms of $x$:\n", + " \n", + "$p(x) \\propto \\int{ e^{-\\beta E(r)} \\delta (x-x(r))dr},$\n", + " \n", + "where we have integrated the Boltzmann distribution over all degrees of freedom for each value of $x$. The probability can be turned into a free energy:\n", + " \n", + "$F(x) = -k_B T \\text{log} (p(x)) + C,$\n", + " \n", + "where $C$ is a constant and unimportant as we are only interested in $∆F$. In theory, the free energy profile along $x$ could be computed by sampling the system in equilibrium and recording the probability histogram of the values of $x$ which occur. However, for any non-trivial potential energy surface it will take a very long time to achieve sufficient sampling to get an adequately converged histogram — the high energy states will not be sampled.\n", + " \n", + "To enhance the sampling umbrella sampling can be used. This adds additional biasing potentials $w(x)$ to the system to restrain it at certain values of $x$. The form of $w$ is usually a harmonic term:\n", + " \n", + "$w(x) = \\frac{1}{2} k (x-x_0)^2,$\n", + " \n", + "where $k$ is a constant with units of energy per units of $x$ squared. We then run multiple simulations, each restrained with a different $w$, and then combine them to generate a probability distribution that sufficiently samples the whole range of $x$. The process is illustrated in figure 1 and explained in more detail as follows.\n", + "\n", + "\n", + "\n", + "![umbrella_sampling](umbrella_sampling.svg)\n", + "\n", + "**Figure 1. Umbrella sampling method to compute a free energy profile.** (a) Multiple biasing potentials are placed across the collective variable $x$. The blue curve is the free energy of the system which we are trying to calculate. (b) Simulations are run for each window $w$. The resulting biased probability distributions $P'(x)$ are plotted. (c) The unbiased free energies $F_i$ from each window. They are each offset by a different $C_i$. (d) The Weighted Histogram Analysis Method (WHAM) is used to combine the windows and compute the free energy curve.\n", + "\n", + "\n", + "\n", + "With a biasing potential $w(x(r))$ the potential energy of the system becomes\n", + " \n", + "$E'(r) = E(r) + w((x(r)))$\n", + " \n", + "which leads to a probability distribution (in the canonical ensemble) of\n", + " \n", + "$p'(x) \\propto \\int e^{-\\beta (E + w)} \\delta (x - x(r)) dr \\propto p(x) e^{-\\beta w(x)},$\n", + " \n", + "and a free energy of\n", + " \n", + "$F'(x) = -k_B T \\text{log}(p(x)) + w(x) + C = F(x) + w(x) + C.$\n", + " \n", + "Thus, the unbiased free energy $F$ can be obtained by subtracting the biasing potential $w$ from the biased free energy $F'$. However, when more than one biasing window is used the value of $C$ cannot be neglected as it will be different for each window. For multiple biasing windows we have a set of unbiased (but offset by different $C_i$) free energies,\n", + " \n", + "$F_i(x) = -k_B T \\text{log}(p'_i) + w_i + C_i.$\n", + " \n", + "To compute $F$ over the full range of $x$ the different $F_i(x)$ need to be combined. This can be accomplished by the Weighted Histogram Analysis Method (WHAM) [[1](#References)]. The WHAM equations are shown in [appendix section 2](#WHAM-equations). The free energy profile is also called the Potential of Mean Force (PMF); in this example we will assume they are equivalent and use them interchangeably.\n", + " \n", + "## Umbrella sampling simulations\n", + " \n", + "Most umbrella sampling simulations have three main steps:\n", + " \n", + "1. Preparing the windows. This is usually done using Steered Molecular Dynamics (SMD; see [appendix section 1](#Steered-MD)). \n", + "2. Running the windows. These can be computed in parallel to take advantage of compute resources.\n", + "3. Analysing the results. Typically this involves computing a PMF with WHAM. \n", + " \n", + "Often you will find in step 3 that the simulations do not produce a nicely converged PMF. You will need to return to step 1 and change some settings. This trial and improvement feedback loop is a normal part of the process. For this tutorial we will use settings already known to work.\n", + " \n", + "## System\n", + " \n", + "This tutorial will use umbrella sampling to compute the free energy profile of the end-to-end distance ($r$) of deca-alanine in vacuum. Deca-alanine is commonly used as a toy system [[4](#References)]. Its equilibrium structure is a stable alpha-helix. Starting with the alpha-helix structure we will first perform a SMD simulation to pull it from a helix into a coil. Next, we will run 24 umbrella sampling windows in the range 1.3nm to 3.3nm. Finally, we will compute the PMF along $r$. Figure 2 shows the initial alpha-helix structure and the final extended coil structure.\n", + "\n", + "![deca-alanine](deca-alanine.png)\n", + "\n", + "**Figure 2** Structure of deca-alanine for end-to-end distance $r$=1.3 and $r$=3.3nm.\n", + " \n", + "## Step 1 - Setting up the windows with SMD\n", + " \n", + "The script below does the following steps:\n", + "- Loads in a PDB file.\n", + "- Defines a collective variable between the first and last alpha-carbon.\n", + "- Adds a harmonic restraint to the CV.\n", + "- Runs a simulation where the location of the harmonic restraint is moved with constant velocity from 1.3nm to 3.3nm (This is called constant velocity steered MD).\n", + "- Saves a configuration for each of the 24 equally spaced windows between 1.3nm and 3.3nm.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import openmm as mm\n", + "import openmm.app as app\n", + "import openmm.unit as unit\n", + "from sys import stdout\n", + "import numpy as np\n", + "\n", + "pdb = app.PDBFile('deca-ala.pdb')\n", + "\n", + "forcefield = app.ForceField('amber14-all.xml')\n", + "\n", + "# We have a single molecule in vacuum so we use no cutoff.\n", + "system = forcefield.createSystem(pdb.topology, nonbondedMethod=app.NoCutoff, constraints=app.HBonds, hydrogenMass=1.5*unit.amu)\n", + "integrator = mm.LangevinMiddleIntegrator(300*unit.kelvin, 1/unit.picosecond, 0.004*unit.picoseconds)\n", + "simulation = app.Simulation(pdb.topology, system, integrator)\n", + "simulation.context.setPositions(pdb.positions)\n", + "simulation.reporters.append(app.DCDReporter('smd_traj.dcd', 10000))\n", + "simulation.reporters.append(app.StateDataReporter(stdout, 10000, step=True, time=True, potentialEnergy=True, temperature=True, speed=True))\n", + "\n", + "# equilibrate\n", + "simulation.context.setVelocitiesToTemperature(300*unit.kelvin)\n", + "simulation.step(1000)\n", + "\n", + "# define the CV as the distance between the CAs of the two end residues\n", + "index1 = 8\n", + "index2 = 98\n", + "cv = mm.CustomBondForce('r')\n", + "cv.addBond(index1, index2)\n", + "\n", + "# now setup SMD\n", + "\n", + "# starting value\n", + "r0 = 1.3*unit.nanometers\n", + "\n", + "# force constant\n", + "fc_pull = 1000.0*unit.kilojoules_per_mole/unit.nanometers**2 \n", + "\n", + "# pulling speed\n", + "v_pulling = 0.02*unit.nanometers/unit.picosecond # nm/ps\n", + "\n", + "# simulation time step\n", + "dt = simulation.integrator.getStepSize()\n", + "\n", + "# total number of steps\n", + "total_steps = 30000 # 120ps\n", + "\n", + "# number of steps to run between incrementing r0 (1 makes the simulation slow)\n", + "increment_steps = 10\n", + "\n", + "# define a harmonic restraint on the CV\n", + "# the location of the restrain will be moved as we run the simulation\n", + "# this is constant velocity steered MD\n", + "pullingForce = mm.CustomCVForce('0.5 * fc_pull * (cv-r0)^2')\n", + "pullingForce.addGlobalParameter('fc_pull', fc_pull)\n", + "pullingForce.addGlobalParameter('r0', r0)\n", + "pullingForce.addCollectiveVariable(\"cv\", cv)\n", + "system.addForce(pullingForce)\n", + "simulation.context.reinitialize(preserveState=True)\n", + "\n", + "# define the windows\n", + "# during the pulling loop we will save specific configurations corresponding to the windows\n", + "windows = np.linspace(1.3, 3.3, 24)\n", + "window_coords = []\n", + "window_index = 0\n", + "\n", + "# SMD pulling loop\n", + "for i in range(total_steps//increment_steps):\n", + " simulation.step(increment_steps)\n", + " current_cv_value = pullingForce.getCollectiveVariableValues(simulation.context)\n", + " \n", + " if (i*increment_steps)%5000 == 0:\n", + " print(\"r0 = \", r0, \"r = \", current_cv_value)\n", + " \n", + " # increment the location of the CV based on the pulling velocity\n", + " r0 += v_pulling * dt * increment_steps\n", + " simulation.context.setParameter('r0',r0)\n", + "\n", + " # check if we should save this config as a window starting structure\n", + " if (window_index < len(windows) and current_cv_value >= windows[window_index]):\n", + " window_coords.append(simulation.context.getState(getPositions=True, enforcePeriodicBox=False).getPositions())\n", + " window_index += 1\n", + "\n", + "# save the window structures\n", + "for i, coords in enumerate(window_coords):\n", + " outfile = open(f'window_{i}.pdb', 'w')\n", + " app.PDBFile.writeFile(simulation.topology,coords, outfile)\n", + " outfile.close()" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Once the script has completed running there will be 24 new pdb files called \"window_n.pdb\" where n is an integer from 0 to 23.\n", + " \n", + "We now have the initial configurations for the umbrella sampling windows.\n", + " \n", + "## Step 2 - Running the windows\n", + " \n", + "The script to run the windows is very similar to the script in step 1. The key differences are that we load in an initial structure that corresponds to each specific window and that the harmonic restraint on the CV does not move. The script below defines a function to run one window. It re-uses the `Simulation` we created in step 1." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "def run_window(window_index):\n", + "\n", + " print('running window', window_index)\n", + " \n", + " # load in the starting configuration for this window\n", + " pdb = app.PDBFile(f'window_{window_index}.pdb')\n", + "\n", + " # we can reuse the existing Simulation\n", + " simulation.context.setPositions(pdb.positions)\n", + "\n", + " # set the fixed location of the harmonic restraint for this window\n", + " r0 = windows[window_index]\n", + " simulation.context.setParameter('r0', r0)\n", + "\n", + " # run short equilibration with new positions and r0\n", + " simulation.context.setVelocitiesToTemperature(300*unit.kelvin)\n", + " simulation.step(1000)\n", + "\n", + " # run the data collection\n", + "\n", + " # total number of steps\n", + " total_steps = 100000 # 400 ps\n", + "\n", + " # frequency to record the current CV value\n", + " record_steps = 1000\n", + "\n", + " # run the simulation and record the value of the CV.\n", + " cv_values=[]\n", + " for i in range(total_steps//record_steps):\n", + " simulation.step(record_steps)\n", + "\n", + " # get the current value of the cv\n", + " current_cv_value = pullingForce.getCollectiveVariableValues(simulation.context)\n", + " cv_values.append([i, current_cv_value[0]])\n", + "\n", + " # save the CV timeseries to a file so we can postprocess \n", + " np.savetxt(f'cv_values_window_{window_index}.txt', np.array(cv_values))\n", + "\n", + " print('Completed window', window_index)" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We then run all 24 windows" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "for n in range(24):\n", + " run_window(n)" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Once all the window simulations have completed you will have the CV timeseries files: \"cv_values_window_n.txt\"\n", + "\n", + "## Step 3 - Analysis - compute the PMF\n", + "\n", + "The first thing to check is that the histograms of the CV timeseries have good overlap. Here is an example:\n", + "![histogram](hist.png)\n", + "\n", + "\n", + "You can plot yours with the script below\n", + "(This script also produces the metadata file we will need for the next step)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import numpy as np\n", + "import matplotlib.pyplot as plt\n", + "\n", + "# plot the histograms\n", + "metafilelines = []\n", + "for i in range(len(windows)):\n", + " data = np.loadtxt(f'cv_values_window_{i}.txt')\n", + " plt.hist(data[:,1])\n", + " metafileline = f'cv_values_window_{i}.txt {windows[i]} 1000\\n'\n", + " metafilelines.append(metafileline)\n", + "\n", + "plt.xlabel(\"r (nm)\")\n", + "plt.ylabel(\"count\")\n", + "\n", + "with open(\"metafile.txt\", \"w\") as f:\n", + " f.writelines(metafilelines)" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To compute the PMF we can use WHAM [[1](#References)]. An easy to use and widely compatible implementation is the WHAM program by Alan Grossfield which can be downloaded here: http://membrane.urmc.rochester.edu/?page_id=126. It is a C program so it will need to be compiled. The command below should work on Linux and Mac." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "!wget http://membrane.urmc.rochester.edu/sites/default/files/wham/wham-release-2.0.11.tgz\n", + "!tar xf wham-release-2.0.11.tgz\n", + "!cd wham/wham && make" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To use `wham` we need a metadata file that lists the names of each CV timeseries file, the location of the harmonic restraints, and the value of the spring constant. We created this in the histogram plotting script earlier.\n", + " \n", + "The `wham` program is run using command line arguments. Read the documentation to find out more: http://membrane.urmc.rochester.edu/sites/default/files/wham/doc.pdf\n", + " \n", + "The command below will compute the PMF from our data. The command line arguments correspond to a range of 1.3nm to 3.3nm, 50 histogram bins, a tolerance of 1e-6, and a temperature of 300K.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "!./wham/wham/wham 1.3 3.3 50 1e-6 300 0 metafile.txt pmf.txt > wham_log.txt" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We can then plot the computed PMF. It should look something like this:\n", + "![pmf.png](pmf.png)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# plot the PMF\n", + "pmf = np.loadtxt(\"pmf.txt\")\n", + "plt.plot(pmf[:,0], pmf[:,1])\n", + "plt.xlabel(\"r (nm)\")\n", + "plt.ylabel(\"PMF (kJ/mol)\")\n", + "plt.show()" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Next steps\n", + "\n", + "You should now perform error analysis to confirm the PMF you have calculated is an accurate representation of the system you are simulating. Here are a few suggestions:\n", + "\n", + "- Run some completely independent repeats and check the computed PMFs are the same.\n", + "- Perform the initial steered MD loop at a slower speed. If this step is too fast your windows will have initial states that are far from equilibrium.\n", + "- Run the windows for longer. If you have sampled enough then with longer runtime the calculated PMF should be the same. If the PMF is different it means your initial simulations were not long enough. Increase the runtime until the calculated PMFs are the same.\n", + "- Similarly, using more windows you should get the same results.\n", + "\n", + "Other tips:\n", + "\n", + "- If the histograms have poor overlap you will need to use more windows and/or reduce the spring constant.\n", + "- The windows do not need to be linearly spaced and they can have different spring constants.\n", + " \n", + "\n", + "## References\n", + "\n", + "[1] Kumar, S., Rosenberg, J.M., Bouzida, D., Swendsen, R.H. and Kollman, P.A. (1992), *The weighted histogram analysis method for free-energy calculations on biomolecules. I. The method.* J. Comput. Chem., 13: 1011-1021. https://doi.org/10.1002/jcc.540130812 \n", + "[2] Kästner, J. (2011), *Umbrella sampling.* WIREs Comput Mol Sci, 1: 932-942. https://doi.org/10.1002/wcms.66 \n", + "[3] Farr, S. (2021), https://doi.org/10.17863/CAM.72078 \n", + "[4] Park, S., Khalili-Araghi, F., Tajkhorshid, E., and Schulten, K. (2003), *Free energy calculation from steered molecular dynamics simulations using Jarzynski’s equality.* J. Chem. Phys., 119 (6): 3559–3566. https://doi.org/10.1063/1.1590311 \n", + "\n", + "## Appendix\n", + " \n", + "### Steered MD\n", + " \n", + "Steered MD is a non-equilibrium method which means great care must be taken to ensure the results you get are meaningful. In this tutorial steered MD is just used in the setup phase and we do not calculate any properties with it.\n", + "In constant velocity steered MD the biasing potential has the form\n", + " \n", + "$w = \\frac{1}{2} k (x-x_0(t))^2,\n", + "x_0(t) = x_0(0)+vt,$\n", + " \n", + "which is just a moving version of the umbrella window bias potential.\n", + " \n", + "### WHAM equations\n", + "The WHAM equations [1] are:\n", + " \n", + "$P(x_j) = \\frac{\\sum^{N_w}_i h_i(x_j)}{\\sum^{N_w}_i n_i e^ {\\beta(C_i - w_i(x_j))} },$\n", + " \n", + "$C_i = -k_B T \\log\\left( \\sum_j P(x_j) e^{-\\beta w_i(x_j)} \\right).$\n", + " \n", + "Where they have been written in a fully discretized form. $P(x_j)$ is the resulting unbiased probability distribution where $j$ is the index for the discrete set of $x_j$ that $P$ is computed over. $N_w$ is the number of windows, $i$ is the index of each window, $n_i$ is the number of data points (realizations of $x$) in the $i$-th window trajectory, $h_i(x_j)$ is the number of points in histogram bin $j$ from trajectory $i$, and $w_i$ are the biasing potentials. Both equations depend on each other so must be solved self-consistently. In practice this is solved iteratively: initial guesses of $C_i$ are chosen, $P$ is then calculated using the first equation, new values of $C_i$ are then calculated using the second equation, and the process is iterated until the differences between successive values are sufficiently small.\n", + " \n", + "\n" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "cookbook3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.11.3" + }, + "nbsphinx": { + "execute": "never" + }, + "orig_nbformat": 4 + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/notebooks/tutorials/umbrella_sampling.svg b/notebooks/tutorials/umbrella_sampling.svg new file mode 100644 index 0000000..2736dc8 --- /dev/null +++ b/notebooks/tutorials/umbrella_sampling.svg @@ -0,0 +1,2305 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 4 + + + + + + + + + + + + + + + + + + + 2 + + + + + + + + + + + + + + + + + + + 0 + + + + 2 + + + + 4 + + + + 5 + + + + 10 + + + + 15 + + + + 20 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 4 + + + + + + + + + + + + + + + + + + + 2 + + + + + + + + + + + + + + + + + + + 0 + + + + 2 + + + + 4 + + + + 0 + + + + 10 + + + + 20 + + + + 30 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 4 + + + + + + + + + + + + + + + + + + + 2 + + + + + + + + + + + + + + + + + + + 0 + + + + 2 + + + + 4 + + + + 0 + + + + 10 + + + + 20 + + + + 30 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a + Biasing windows + b + Sampled distributions + c + Free energy from each window + d + Combined free energy + F(x)F(x)F(x) + free-energy of the system (unkown)Umbrella sampling bias potentials w + i + (x) + + + + + + + xxxx + + + + 4 + + + + + + + + + + + + + + + + + + + 2 + + + + + + + + + + + + + + + + + + + 0 + + + + 2 + + + + 4 + + + + 0.0 + + + + 0.2 + + + + 0.4 + + + + 0.6 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + p'(x) + + + + + + + + + + + + + + + + + + + Umbrella sampling + WHAM + F + i + = -k + B + Tlog(p' + i + ) - w + i + + C + i + + + diff --git a/tutorials.md b/tutorials.md index 191db8b..5627a7a 100644 --- a/tutorials.md +++ b/tutorials.md @@ -26,6 +26,7 @@ notebooks/tutorials/HSP90_with_ADPMg2_simulation.ipynb notebooks/tutorials/Histone_methyltransferase_simulation_with_a_multisite_water_model_TIP4P-Ew.ipynb notebooks/tutorials/Histone_methyltransferase_simulation_with_multisite_Zn2_structural_ions.ipynb notebooks/tutorials/Running_a_REST_simulation.ipynb +notebooks/tutorials/umbrella_sampling.ipynb ::: ----