From d2d12796be2c71b27047a75c961ee07ce964b53a Mon Sep 17 00:00:00 2001
From: Alinson S Xavier <axavier@anl.gov>
Date: Mon, 21 Sep 2020 11:41:41 -0500
Subject: [PATCH] Update docs

---
 .../ex_transportation_amount_distance.png     | Bin 31793 -> 29981 bytes
 0.4/index.html                                |   2 +-
 0.4/reports/index.html                        |   2 +-
 0.4/search/search_index.json                  |   2 +-
 0.4/sitemap.xml                               |  10 +++++-----
 0.4/sitemap.xml.gz                            | Bin 197 -> 197 bytes
 6 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/0.4/images/ex_transportation_amount_distance.png b/0.4/images/ex_transportation_amount_distance.png
index 8c52266a5327ce1d1b025045f433b2c492123d95..284e8911775fba4ffd156acc71d3096056d7545c 100644
GIT binary patch
literal 29981
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
b^S;P%Rd>6?0N*01v6QyU7Nsv-`^Db?)Y5V)

literal 31793
zcmdSBcRbd8|37@R_c$v}QfHLR3JDqQ4wAiBDuj%TgpjkSG}Mu;jI69fvUg`vA(5G#
zvUQN1{d>L-o!51Kf4|@T&wc-OUysLmRUG5<d5_oYx!#|<3TIEPTE2BTg+f_HJ$+n>
zLRoN&LYc3zbTNJ+R>;+WKNi{?rK&8&|E@2+cnAMpW_4QAhC<o&2l;Pa@$Mlh{P2+N
z2@P9iOCwu*18YNyxq+?KWlP)3Cg*otHMF)dv9u86-_I||yW^6rt(BO7z<+<wZ)t5T
zaD%e{IEAu<LOp&&<=WF9P4>2`s?F~PIwPK}-no+_Me$bo(LYW~FOEE|ykUc);@XI%
zOJBTxy)^v%-~4~h7rVc7-ift~j>|}&v-RH1CoQdD+Qk>~IQZ$9S59Vu@G?1?6K!%j
zzFn(G)G1^-dw;>tjIp|geR7o>aMhI8-5H0n$X_ToF05TTkNkxC$N$g&%oNR{oD!5%
z7QgzVJj<>(#k}Dlo0#qCy?gf#4h<<cW!Y6HXp7h}>Qy}qHgsucUuEz}W}h$g)XH~p
zempkT*A%x!(CAW$FQ1HzjMC}Tcj{A2!o!Z;jy>wW{KRNUaj}w$inlMnZfr)zA%|<%
zxc>a}sQlr9TVl3dR)vAA`*)MEG&^vnQix6W)-LnL3`OV3(Nt&sR8!UQ$;sZgch}3D
zKK+QJ$$6}4qAT31t+mylRzzxTO`?AOYYFP|l`E^>v%BhaWyGl`)_i!p%g4tjGBk9D
zyN5^5&(;DNIXP7;tCx9GgR-g#TB*|c_wTP9>8+J-NHc#D7Z+z*6Cab3B2-vdNTn@a
z&HCbV_$h6pGvtCc8i{4%g+b;GX~N;ppMM<cENf`e&bgMPiJMMVOVH}b?$6T>wZw;h
z)JioCc>j<so4#K@MAH1=<uB#&s&T%e4ucm3d3Z{M<SNg|$Q+m)>$j|lRV}&x^Y104
zjg5`-o%Nj<!sL^Ta51Gfm#nF$Cu%0YQ|qlyHRJm|DmD}LOLy(s#lpsxAn828#l`iZ
zPcPk~Y51dH*=gEFew`Qipr8XC(IGCexD8>mnlojRlkts>gKB*f<Kx}aV=aCmAtC24
zTo?(NoqA7i86WBtcAdFSt-z?-mGGs1=}R@MJ-cA>%10b>&%~<NU6_wse|a!^&8@t=
zJZpP<fkBtvngmYjvSrIWy}a`GUZ88G%FwEkjmzeb&7VKNDn@w^wW8REhtZdyoqkqR
zQ!`dCH!D!YQZKYW+)I+1TAys}WiA@M>-|D}?m6?b>`N1O@7h%`n(F7L9%ddTA3~qE
zVDSt6e3yy$QZr$kvc6n`g30A+(Py7k1PB^)Q00OS@}<blj64&!uh;dud-pL%lglK-
zeKbxbh8C+5bH27laqf~OqgxDzO??IQ`Kg|F?mS9Nv<x%P8}Hbb-M>jdFMh9b6jqL;
zQm*63k3Ke0>*KVxzCJpxd(%YD)C1jzY~oSz@w^Qyja*uKs^d0kTBe#-+fMzu!X|nB
zOW5x(Fj|^;t}Iw0ZLD+gs;w$tUE<UdhG!=G%|?2vF=2iOEgD}?pX`n?t&SDD^6l2d
zSbw5&^x3+RqLxgd9XmqH!+9feny8$6MMTuGt<rk$-o2ZaccLiY&)d7Ld_O588tiT_
zmv)wg)V?$*@Wvu`>dQPe*6d{Ic2LmxQx#T!G_I|rvQn9aTctdAtT`?*Z$ievz#!||
z!1E}%AfwtnuFHCSnzeJLmfkDzi`SEH86LL1{cssR`t^jy0j)c2Z5LOu9#YsNAFP6b
z7_QN_)K#Bd&cc1EJoHH5K7+sVW@nsoN9)bf0z~EI<*5!!ayPXPj;$GL(6?+UX|cC`
z>tDE&hv(F?Wif?fq}YEw?dH~uMZ%Xf;J<U~rmP>o$?F^Q>a*<=EwUL0OP`7+f3RPY
z7;)wMJKCVHS%*NK_e^@uf&Kdxqf9o|i{$6tyLYeY%goHo+&HxSXDa8n8dg+P3=dbz
z^X%SzQrNVrJYF+dCGYz9HpiNFSza4!>&yDJFBFd{HQ#SwZxQ%t|KrPks*(@4>W|<j
zEn{7u!%sX6aveVAqJ8SY+|4h&H7l@d*Rf-_S6BP;X>ZuRo&Mql*P<m$T7C|>%ud@=
z9c1~3L@qy$c=>Xl`>k82X=xTsT9;a;dLL{Rew7_OJ3Y#1Si!LG__&2l$|Xly|J40|
zKDIbWberV$4D9&O@^Xa}Cr<1Y5*qdh@q6|xK{MHiO2baz7ZI6M7e-;_qE7V0B`zP9
zJ99?G);5KsZuPygTDq=yW_ETj$`)#-vRmG``12a<q}TiZc({2zhWJLRsPm4GMMa-+
zS0mrOq___q(oj@XOcNZZw_yoXek;7kczEg2;A%Ja{pW9;KYzZhqazBXcVkyWzN@Q)
zgM$gG^2E=AHRiH1Po6x%SaNah*%N2clx5nGmY|#O$->j~_|*2t91qx~^lq<ad)1_!
zZt+ZVdRUoSAy{_!!ri%*8Dy|AwdBqdjkL=FCm(F(q%L2xMm<u-$Mf>!w|fGy_%vDs
zzSNXapK5Jqr&=AW%CdHCD3%-ck4BV9G1hEi{!CV1{_M=r5K_w&!%yxN7uP;=<jC?>
ztEyWIZu<lV#^PE`n{yo8KV?KlN5@&V<kcr#xUHkBYu8|&zE@bddUSh>vb;oO(uMb0
zMjwOj>YkiOc|CGKF8PDp$c=C3H=lgm>8dYB?LW{n>}K`(`3c8X_f7N|##2!n+xKkt
zr)e$|-Fuv8r^h@WJgBZqHuib+XotPMy=sio2|lfq^7ZnE!?1OA2OOM6e|*lL84)mV
z%2K6LsmqrwQw%z2E@a!KuxQaDmO24JL1oN<R+eqdw{PD_84<JV>AJfo_$A+})Czx*
z6>e)O6rB~7LO#B}&#S677#bVv<t|WIsiULQ-rmk9Ai$0msFzzXyKC+I6Fb(<r`(9!
zFQ-hU4#>#LW;$L7y|r+mib|%nWNlSi#DbkmDi=^Fp&w7n%cr^@(Qg^#R{x~!(K_5<
z6#6!xxVTuw)b!PX0~Ox>*YxOgi&|l24W*?3V-zmI0|y4x);l;&mekg^{9XMzz`@b?
z$?e;I>(+hRyK9$Rcefw!mZjrmoWEatfP<>1*Swm(@I!;nyM_jNrRE>0EKE?Nu)B@H
z6=<JQ!(QgLn6<E}=@`vBDCj~Fo8>a*7p?y>`^x!(_RIp2mRXlg%%4#xCFH)ac%S_F
zKmJ@TWYdvf6|1V8pfR9(_rA!LZwpapRT|PQ`5q6PGryd_Q0Mm7b5f`LD6f}275Dqm
zwT|+7r^l*o5&r%RtqiLeZuQkRwxVa<q?h8u50xKVBk_EcA<oV9;{4tFW5bmN!*AC+
zV?Hn4y}!f^qbqXmCyzeQF2RP+h7_)2hb0<^i%KL|br(~XEM2)$<=nY*cOR%Hoj;)(
zuW_Jtea)#I3oWEi8l@e0Wldf~$yoL&L@HV!&p-UZw%Xnwb(MoZf2tfm&L%O@wI0hf
zQnvx+y{Gkdzk2vdx#4Cf<>5MG!4!+8G4x6GYu7S@uRTu`yZYl#YJHw_-1Fx~rY(87
zv<RcpzVbVNgl|}<RMdwCHzS*DG_C#pU2Z(TZdN@#Iy%~H;9Fv<<H+)7Vs<ihb(-Az
zd4E}CwyW87m7ieLH`yFB-*fh9s1J{yNwK$lRRpzizSKQY8_CLd54PFPOlkV?bS7Xq
zc7HzQ6r-8kvB>3Wf|juArAvm+Bh~2>6TRbDws+44ALeIg*H684CE8=<7W!a2kIqQT
zk(n~#mUeyFiZ|}EBjcUPBaHNWLe^~>62HC{xJw$heQ2F%_j}+t$yj6C`OGyr?#j$m
z;l$KXo##V6I?w>uzLz<DS#b%$j;4>Mrk1<%U24h_#+N-F?Qe-59u{)HrJ~eZV_ubQ
zF9l4eKVsvvc;QhpiwU_-7e>bNrQ+VcJ&w6kEe&dkX=~#^B~jK+pLzbru9LCGWqOMy
zu#I{%J3V^3KJSWEPs~H_kHxBRWTg6WQ2Y9}JGT1_OqA$bs3sfPccr(C_TFZ%>Hhln
zf<TE$SqDc)y(D^Lqs{|X(KFds3qQ0-Nw3;=kml#-_vx8<G@E!DkAy_Q#zA^C!-rMO
zR-sH%{P-q;cRakjIw-}8*QXYl*S(?!iCC7Ghn3;Wo83p9@x8;}y?QtNp{QOR+Y}?=
zbk(fTvp>bMMbCMnTL(K_=gJT3_MGa>A?NxWhwyLT1-kmO8)9`tEwd+^vZdlJ^K~Qe
zpUR~jhn*+9(Qo1(J(5}USB^=b<3M2&-txpEKQ{*GbY!-l+a<=l!R7OCw_tm3uUW0j
zx3|kM>ilTY)iKKQZf<T9fO*61el{aRWm2XS!}5uHe`v9hGDJDMS9pZ>&Wk-fB7)-q
z+oXJxeanIaE057OY_dPT>(uJn6chGXlS*-0Ai?^P2M?MevD<n}1UA+AI$7YJ%cP{v
zgj_$M+TGoa%Tlk-b3R2?GBS!n51?b%Oc?dmR|VbN@7}GW>t>%PgHah(`Y1ZukD+(+
zWENWM*fvw`4V6M8J#hj(-wLnU_0PNvcCtu8QRi$gwVj#nFY9?CFRAqXot#SaS&8ht
zX!#HtP`OcQAh3?vX&S$-%x9ajRn>|4eE?Z;WH{AXrS|Pp`2JqL{H4Lo4eYK*$_@|d
zxXBsLU$CG$^hm_j{^rOpUz%d|^WB=JBV{-70B`ALUrnwK?*AB2SzJ`4s8Zz@tCboU
zk>fgh;oadxtfGn9{3w&E7fETO`p&}gpFfwV=DS4bIkc~8nDoue%$&gTtZB?l7IGML
z!a5V7Pb8;`J$yzAoU&HllsK@dT2t1DLM^@NvVj6ERy8iHwID?O?AeETlNMCBJbr%u
zt>U90SNmsx&vnw9)MPt9JyR|5wXc5@%7LZw!no``NBg3TI4YqzCr%zrS#gcl*4=Hm
z$%7tku6Xswm#76xT$B|Q9(k;C`oymwY*L}J=J3x@Ya5%9k=hl@8M9ME7sxkXzkYq>
z%LV7lWqF!e_GLj^bg=)LMt=Ob%%`8HLZ{QS`tz17XEdbuQ?xgGb68rkV?&(uFt}9c
z83~${D$zSs77lh5rmpW?X)(mMY11aa#pAf>iZxR4s^`zYk(<2y@aPUe`5Vfl8qgxL
z`%IO)rae{#oi5f^n>ZB~<^z&7GQYN<AWlXptiPeXMcj3!QPnJ)k)~yR<;v&5cG;08
zds%O9?`z8S8x1=@u`xeGyUV)f>@!didr=V)5n=O*+WECZ3%;dZZ#J_VYhrBJy!l0{
znL3Z?xa+Cmc>UQY{5ppc0p#``Iuuc!H`Z90^g31BA|@tK*i!lANe_l@S&M5+;=N7Z
zS^iK=e?1wjq{nst{^b`>pRzI<#(L!@E<P-vDU#w7i4snwVMTVaG_V|8p`xMiD8jnE
zn8iVAR?o<&L)9z}3k8F&$L@Oggk}D8R<ncg^H}xSdx1ikx**6&K_l70X(x)-nEUYD
z-sC7X>uAu*&-LPYW8?C7%PlSY&1Q0Hiwg>l>1H)1It+DOs*Y{%`TSjxT9Mw;QM$R=
zb@rzF=+MZ>6E82zu(6}Z3Wg{9^XnwFXZj22y8D4fOv0Q8ecZPkoxc-T`&7xoqWNJf
zO44I5FZsue`SWG^PTwgR`7!Pf>=->eGq%LMY2w~hMt#_cdmBwZKX(URNcULnJnB)e
zS7aDxG;5W6XPbJaI%}4l)9Im3S2`&|+a<QAn(tn}RZG*p@$<LErb0v7)QOh<6Ya&V
zrd2NnSj=KnVg^TiEk)<bbtKA^=RNV*Q|!(<j~_o^)jb>b*Ue+Y<;NsO@SjgmP+W-X
zOroBHVNOSBP#nK*pZbHXu9;zJt}03AUq<A7XJ2m9Q?)Gn>cb5iH`4QGQZo;l*M~M`
z+nauWH<DI*QAcOF>n?s#QK}z*<OVU>YZJE3_s`AL-5*cRZf$MdD&=x?;QG=Pt!&KJ
z5t%<D+%Ex4Ikx2eM(YOvSXEggO=)8ztJ%b`ykwLLJRAfKq^4fd%Q=HTf9Cm7&$0=K
zkE(R`lTVpbUroYo4ik(LzP2wn{b%XL!35n&XE(FkYuGE?7UY*y3ikh?Qe%~)gQupZ
zQk}-m>gH^A-NhcRvXg+C*Lx*?zP`D9dF%`K75P;nExZa>uckFkW3xfP$SZ%K;@L3D
z&>krf2wJ`{{MWA)_4%$L5woQib>$nL3t3#xMrn^+vFVf9#PHtY($dtXhD@8=zP#gF
zC>B^EkEN#T=p3$#2R}S6P`_OJ%8<w1L#<}4<y7w*_aQ8dRCA9+E&?6)oMlaS4gq*x
zBYEvqlu4{j=VTk>S^DKKO-;JFPGhRr4uA#;85!Y=g6%p!nmA97O!ZD*^L;zF0XTsJ
za;HZ*9&8!Pk^J>lxAd8~c6y_dGRVJ})9C$g-yU-B-K)6k<bB@JfFvm~tFIz*0SBn_
z=FN-M&3-t4K?x6jD{kMXprsXv?*G6%*}vCBdqcs#;R@Nr?mFY!UA>8&X5Zh1U?ZxN
zmb%+08&yl#w(HJ(<F(C~T_+owv@)#&^qfadOphemf2ggMrwLvBV3lnzs;i@8J3HMZ
zeBqrf^@Qc_Cy7dt3QbqF`9}Jt?*tw+-z_gM!1$6Rw`|!a)$n(GjuYJmR~hV1@#%!i
zLzszg&UK1aOQ=W7)$!xkg_;nJ*+1Ug+?*z7E+aU%qtuQc*FABfwDyg=zUlNtNQ#sF
zeO#Vu*wGWDvqITX3p&V<&7u49%|-#A6u!M&8+L4okH7y8*V&xc_ASn9x`Lg=niLv%
zGTVK%N9v42%sxHUtj`!Qp8oY+jDRt8vfjt19P50)Y>ci+=&u<no7DwRuJKsa>k|;L
zlj=BFG_&a7m`VL`V&MJ@SwOh?rsf_7U8%LrHBUuDOh$Tq$V6bM<4$><8m>~7FDWZa
zl%50$inHs@PPOg+lhL#-uElj$E-%kz`Rdg*H`k0-HQA@<X0kUQSy?Gm8Yi-VRbY;_
zuTI!`=urQfdoJHQd3N;{n>Eb)>Ub>+OYv>aY{m6Hok3Nt1zcw=Ea;ztC3b`O#AvlG
z-o>>oN`6*hsH3#HQeG;&Id_t!j;<OPwR}}VJUAVFVccX$?{x0UmBYT-*=AJl-FNMo
zTB!GdP5e)5D<bc;cX!7C9f)T=ReHb~jygt>aYrre0ywKrGry;#q%_?2WSV7jm%q)Q
zCCi!fazn|Wz$1iZeX=eHA}L}MBip*VXfhK2{I;iROKnqUXGr?SW1NOd`u_*X_}@v#
z|M!1e+t?C$M%rXO>yOT^bu->JowR$5I<V!c!S)u@_Ycj*Y&ueKBW>Tm$D#YjT>0Km
z9a-Xx<##g7*}m`oXHOQ{RGZG#x*1k_Q6}Ik&$k}D9PiYhs}C5;pAupc=n3dW3g=aZ
z=VwTew%tmeC_1(c=BWhoWOW9gJ+LzTi=@5D3DSKjKcfj8E?Co2o8ICQ4rH5|k-^0q
z@A>9UESIRL=Hw`&I#?oG*s_^bV&J&`s;xp*H6puq>00KE2iC-Ea#Fd~=}+<65BpX=
zJ9Om?kJ|NU7M?ui?5k`-7LBrl!^5w(IW?s5Ire4FN(cZ2qq%ig#XPBhWtg0Hxh`JV
zOs#vQw&n5d+oy`Aq-B;dXT|E~;{3tX0|%1Xbl(XN3|m$15g6n0HSX-_Fm25ET>rAw
z7-B?s(Vod(w<X)X^IdNw$SElits|V!7qq*yUQtoeiOH6bO4QBv@883B9y|Ghl(X*c
zz0~3lAIf7@d4$aCFDB?_YoV0%-dqz^R9#&?iZ!m9X`SIXdi@Ne!Cql}kmd5&^Kif3
zXZE{Iv5JI2IZ;u5o*&=ht;XzOUl$u*G~(IC^Zv8pp~f5sn-qhBGH|={wxUYlzKd=L
zXJ+R0)G&5}a%u9Y@uupAh}-+7S+;PmS+hniP)H7XUwUsRR`q0mKV920SFYgpnhIRA
zuzerz2t)jJO_W8G<HTTzWm|{ZzGmAV+eB=q@GXK-z1jV~UER?kkMFI}j%oY8hb*eE
z9+6Q|J@*7UPSYla9b(J(T@$smv>fRg=$akNjTj%2^5c-0`SoPco3HKI2#I>R6Q^k%
zWwS?PVq(&qBqj6QJ^sF48kFwsEg~E6$ZBA#q|eYC_s%eYXrW+jO#{}hPG}h6qc&w+
z$t8=lrzf_rDX}@-X>2<nnWBu$tAiFguBG2E8X48+ebV>zJj@&>iU{wl^Xsj`7K-Q2
zeYG2D%600T9h<(#t+F)BbTTy56GE?tZj0IDd`-F1z*H=KCtYD*yWem9(U>Vn8@xK2
zqi6i7Z7jjM)ER`$RHU!^M@zoEtnc+*RL5_3_ar92dF90<^Itu5vuvrfHim9r)?`Qi
zl4}yqB|bxG+s0(ToGxJj6@U7qM)+f%^ZQ<UQaso_1~0=vQc{u@QB{@F+t<rrI5#<0
zRwyyv5f{Sqq}TQ^LF2P=R~cekrDocD>1A8y%$mlRU%$%GB7pq#>{}i^T1%}cdh$Lo
zvuxn|`ycQ4&X}6U5_Z$#(vX-x)xJ?KaQKh@)f?v|hp!$0=QIw8S_;s^MXJWoojtws
zt*S={1~!3GsnDuIkF>tmjsT7S=--)QTxJ0{EcaxOyt?%35%a6x&oIRqiiO5d2VZ+<
zXCe?OpXT6*-Pp*$fFk(9Mu9xX7JxVIJ$p`}1)F~U_G$hYq?}<d*ZV4GK3-L&vqr6v
zn$kFOge5U<xA8G%F|aDg$;}=4_1$5~yRv|xfb$pZb(5TN8+qeKZV@>P+M#E0QYXIM
z<6_jU*S?r9;dGu92C7n7aBdsJe0H?~fXmEy+5Y;hkxiiK6}Q=4Kt`YY`TV(t$su2d
zRK%&Xr(Uj;2?z*4O$Z~jA48mC_Jl@zZdl^`LO$fwaL8<Ys;(=#8BpWh1A>CW)@_1X
zuiCa5UcC6F&-miSOWhTPTSW)A7#bPHDu(awsqEaFZQR+`*5#u<69a{Xhl}epyUVYE
zRctp~?>DmQVtOeGS`Loh!TD!587BZ1IevdIMkp9j6(q+m#u|O}r~mxPJvcI=j5Q2V
zBMiftnUzH_&}HYQ#zv+n^KM%rq=^0z=;)^PDMicIBytygXgI!`kI!;b1;D4-)URdM
zHp#QRy*18>vs1<oIEo4ilr3`xWFDtV&Q7(c#;G0OKea(7x?*VCN?eo1M-(<I+hxA3
z5L!Qn&xS2wzpep|^)obLTL7$QhaHYKH%ofnc@ei;E-+Tsk50&@uD*bPK<-3OkmJw4
zZ>OFww66!;d&utfghTbk+KB9a3!?wTqHnBV6Nh6oIs#uMG2^?5j7+iIuN1>2a}yzF
z1D<aB_Ku=RRXWBHBVA-S)>{!7mu1`Sc<h3h_*^A^_UW1IRoi8+<^GO3K!)*a#N4v`
zfBus<yW|p9!ME?<S=iYVKYl#3Xz^lV-eGL*Y)!~#DD2kYUOO{bA~1mhmSR}4vGCnH
ztkP)dps!!g5!<OWP*@ojm}=g2hb1b+8>U2t6f7{nP9!eXq7@svpkUKDDuwP{b{+kp
z2}Y{JqZVJj%`zv9_#9pmqy9j3T1uSIJ752`vLNF}_VZcEW!~|#)BN?b54CO<%qI&q
z@7K2#&Qk;LWzL-OHVGWWwz+sQ;?G^XRMRbVeFXIN08Ix62bIpBf4*+rI^y6!NRkCY
zt%AmE-ulzhbu#GP{Vm~v!e(MUyHJ2%yR9sEWROuTWaItp86Q;bQ+^A%czBd)ZQs7h
z?8s>(HVa%!vaDbPX3fq_R!7NgBl=FNC8{w8_0&Vw&lQof*d7O_$MR>ZCq{aOuY5ah
z2iGj4WC@t^BFInN5)#l*V$fx5ZAGoDfdPbtHEC__?ToLc%R666UxTDG@}o`}9-vx#
zv5#ff7Giqb`D2&R`L|0GG?I>1M$6ZtKv`NxVqm%W4ol?v1P8}fRdJy4zt9n7-?DgH
zZ+OJN6k($0O0K5ISgl@h3*c~i)sny8*mhT(fL2ih@!PUq5I3)ob<M$nN3c@e#AL4w
zm8u{k^H;d+{0(arKED#I!5c*cS9S=lJO*PWtGjFw5K#BI%^p+JJRhI}$HeSKO}4eA
zS}F1K(=q10etuqt1)&$+h%QgL5mdBqCFJKKh{;hVdRLY>g&t}%x4M|S>f-VX-O`(}
z%+~KY%OxS9i-iMGm)w@2Or`$Ed8b}p+@X_wH6iNkvsn1R)Z$6@L120FvGwcMqo|yw
zR)BkQSoTY$U+^*sBo;x9ZQ8_|f3g4x+R>P(?((o>xTDALK6`2sh}{umR!cuIV_@A~
z!CC6R{}{|W)crl}3`PPZub!Cb;0iYT#w&$MBIflGux?Bs(GcrcL&G0>YQ&M7i**NV
zeA4FJ5HAC*%d4HSjwZg|T=OGpbX7q)ps;DJ#g~@`TDWv<{0JzEvoZTcU<&3rPuAxp
zYNf_bO;6ilqB%L*a_?LpYqIYp4yhII$?Mm197lR00V7JF6<{-|;3sE8B>BLjV6XHH
zyk{4%ZOpXkH2wDW?g2UFu&}ULg|NR?vmOe?R&8?ZO@Pf54E<}xFpv3#W?oHAQ5fcY
zHT&ti4}FoRRas75H@w(>C}ktX@LqIwoRQph6`F0I&a0bo^C*X8&V{BoHp%v_l#^xr
zoo&;3)*1FROq}W!0y&{@Ut?hNyQk%1;Tr}<0j`ZjzZaHMR*hBp{A=KQszJeG7+ojt
zZRD!}-ya!muq3x2HTCmm)R_RK(0;te?$=L)>Ns_IvzqwNaH~cN)<|_#tLyui1O^_u
za^7tp4>c(%3AJ5>g9<-0*5z005<a~g4ZK_tCZ+AquSar!eY@vgqaFB;K;Lt^zRPdf
zbbNfwAu&B%3Hr2W#j}`VzuB{`eNEZ3!x@hsKlXh1P%T8#dBcVc7wr>aXE}BRz)4=Q
ziC+cOhS7}0lxoo=hMm)ObB*LnhL!1NkL?a^e}K;~fIbMFwQ|LMQRfNU_KuDofYtI{
zUWd<XKh%m*;spGoq7!N5I;NV}T{dB3I&^lL+-ofw(&T7#lWv3YL2PP90u0-!?kmpD
z&h34DdTrAfH(44A(gt>R%j`VUYHq3$2$d@CZ~ip-YHEd-)Xa;js#!j}9NTWDQ$_l-
z#ERiK#c&T|B2sZvY1!(($G{w8u!&#ik(ZYjx5^7EIYv`c6JiglA62PawrojD%+1NU
ztpEP)+tW0Q{OQr7lP6A|EQTO}-(4-)>pDH6jxJ1eDGZkTXsK%l7Au497xmlgi=1ze
zY2EG}9Bh%!o6H5Xnxs0UrKOW<Q?HL(Q<aV%zjfW&*}T?^RrF7)`=>yvgPSlf?-`mc
zX1ZZyDzV_r8_%Z!@d!4!xkQ>X!xS|}F&FlrUxh*HF`J#4hN|+3rGaD#Pz(S3^SOo@
z2?}(Sg$Pi$3SD~Clnb^^%{tFjO6+mlW7C5TzVG&19<;YtZ{QE1DEJN-vr$4LG)z5S
zVu@l)2pWCNIG-JU%BzPY9t<{{!dOkJwwal70K+<iSOO@NlWl+QSbbBOzKmleOl_|i
zm}>c9E`9>)eCEGn53;3eNBf$z!NfA3hlj(ii$pr%OOw>qAO1)d&|%ncgI;0rD|&60
z@Qn2RKMi%3OW#rGQ&LiR^4|Lg1ne!EX*x!{^sFeCadX-4{vts>pLQ<1@$IeXEy~v%
znF-dTvWt%D>+8#fNa`YmQBLEOO}SXKt|1qyO@mR$nM(Lnp(uq~UqgQdwW85%-FNN=
zt}(8`B3llt43fpZko^37_~pxalX7%sBwSrx8&aS98f~oU_bL&Rt@OvHp~ROe$)4nl
z0j<`0b@6UrX6N=T9y=?Au%+?Fi-A!bF(|dL*bI_#r2Kt-qmU=j+P{B4keUY+jL5<E
zl1=q#z{T+KUvAvZ!y}6fL5i8vcrE_qwXWeq3y{vQI5?N&Nv>LHkoWVa6{MmQNI7`k
zz5AK?txukW!{LoZMxypQZ{Y}`bg0s)z!L7aZ}V_-%l!TK-zU;6t6n@lXxV&OTx!4z
zQf4G#8EByO<}_t=cv$5;uwRis;vPP9d&>AAmQ>YTz@eU3<k+>$8#gFTcD1^WzglmP
zAn-vNNa4oC$**1sUH@fe{^jKn)J{)NPo+zjx>zP{e|%A-rI=Jk9W^f7$g8nqZ~r+b
zc6Rm#JNzGfNg3KO>J&?tecOjW%<EIAG=yEEmBfGFqwNmfy&$YxB^*;+rUp(SOh9e{
zXff9`AJset>k_(NH5{2l*kdxqPVcY${nsL3*BI!OAf%7xJ3~O=Mu}&nx0vErY3(nK
z%Yv&(fC(xp(BvkKjoS6UYo13y$nvLOUKy4M!N8|Fl&JDx5ngQAq<>uzNF&u5SDg5M
zyVDt<5zzA6B-M0plRyuy7;ew^_g?D#&ABU_Ykt%vk0A9?BqXOw*U@Y*@vC)Pu*5qc
zAO=)NfTVW91fNHme+(*=$-Y0jO-g@@rs(Q~MbdTOy8B`^*R%V)<qxNP{rJ?;PjRnh
zjmf~bLan^(nQ-_LZ{1qh-nL<SlV!oa6#M>WDPg0T$IEE8=ynhoo_|OyDjJ>LqZ@W~
zk@HZg2>g`Ugs!ejY=^9*p~smvWu=m|3>wI$@pyF0Sj_vxkL0oxvs!*gCPxr)!JRxI
zshhUJl7Cj&E37hDQTS;@X^=>-RtfGje`dmLzxraHa~^A@HQ%k=Ns+c5-0}w5v@Zt_
z0utPW;1nn0!(CLJ+UBx@?2E6wyev!A<280-9uTRzga-bQAE=E&DHf7t9B>4H+~N`D
zGCd)h#mxS34e<&e>w-7|&E?Z8Kvl|(b?0KXyunov;RUSlAwPf;-hNni(Hp!ELtPpy
z(eRnzHi~qBag6kr=O<P?*e;<3**ag?yk00WGEy{)gZ!E+nRjHh0Xi2)d#>yuyB-w+
zQ~(EZzKOeg7;tfO$41DI7I@=8fs)%#KYf>^NlBzy!0$58vls01O#bInSeA-95%-TG
zvzkd9C{Mj35BdO=Q7GQ5OpZV~v{#mI%XB!xaGbk$bBl{ldNSU;c_Z`UPx2xzao$Z!
zE0Mqf);FztW$1bDUbd;z+|;gnL0Ax_cq8r)rXs|N?~sLWoT<!-lB}&?O@4Q-Ov%k^
zVz`^wlIWpPXt;5(;1HyE3~w)7mN{$(-s45Ueq?>Vd!P&~&8o|Mx3`IJz2Wf3072px
z!QyZ0Lc)|}AV^t}mc9XQ2}!a0Uq5Zd4x*zJKNGci_pgCIWc5`VxE-v|<lmD5fZm&s
z-dur73$^PIoA}j_pE=3cNCz0k*e`8JHQPfa_y<@e_1eJsMGF^xc>g~7gCu-1TrQ_7
zbA-INpaa8+=d$A4x$_97{lw`0mEnhEi7Ij9KnbR&RHVh$mc)c8Uxl#7vhDl(5NE*u
zUYlr`DsLfwlP+R935ZF&s-k_q9%a%4`v+Qo$%bv);(q<QhLwlH8wc#!1Md?Vv-ciM
zKKFBv2LIY%DOWw{^5u}bIojO|uA7*c0H}JaCF&9Qd1<h%2x9P6l^F6x3bBAFMj+m<
zvojMIEEIfDrs`LQvIt4a&;T_P9&8ga1>{9mA)CY?NwRGF_U)_btmOSN?3iqU{3#_w
z82u6x6PumKbW>3`rGwB_&q~ew3P)>*oSqyro0%H#sf_ko5KA_}jfzsGpyGI)OeF}~
zk$!sILMuD6d+FIQ2L!M$z-yi_<Y6x8S7bq>89;njhFDLpPlHB|U>Vf*+cKfdo91%D
zC{|WhqHu|3X6ia~#svihA;5=l!SFw8ayu>)Er#@H^ralr22?&c6jT<-cy7hyPC|bq
zsqDC1pAvJXvMR_j&&0m*Eqg#zOnS4UtcSr1;C@bxo#b`iY?$BaiIFD;o3)aS9$+ye
z1tP)?YJOD;-EZ5$%L>@1DMqDRF-a&{V)S$5ZCr)Cc0Z0Ix*>G+hej?+ZGDzqT(D!$
zUcw)*j}Kz84-5<dWG0nvf4D{Pq+L(d6{~9UP6aVck&IGHo-<IP9ayK6*tMUbuacAP
z`Wi*E526ZGfj`3xwHJ>%&HSnb*rS}J&6rk3Js>ss%NGq&Eos2L5m@9<zUo)g=gNST
z?BX}q5%k<W#a!t7ld7T)Kme;otd5>Jjf9jCuH<|?iPcbw`AZhP0n*X4nMBt%!|o~6
zKx`XhLXbE4%MF@x>;eN&?86cgY$Pg!-^oNCTuaAHWA>E5VA*t;5`eeN>Lx=W^hE&n
zr0lB$-%j8n=pQ5j`Y=a8mIqeeOlH~zUl)rCt=+w64@vu8t+lqcUarF<16o0<@`h7$
z5<~}H0v%QlP9Sa2Xa)#rkCc=Y<^`YVVF2$)9bH?AbnaLca#371tXr4v`t#2XfBa!E
z>C%{S1<JMx!pdwKEacaRmfT+aMyfvDG9+A<{F@T3XllQOS-q!3!G4WDJ>Bcu87$$H
zrV+e?{NC_E!TeT<vBvOPeb?!zMFnVKBoeKUY>k}5cJc~uyVXv&_i=C>CkT@09%<$c
zvAAQ>;u;(2xe<^O_;j;WTAat8Av|_*vj=2RrTeO+B1+e_zLd_eZkK@vryg>B@U9wN
zCk9`ExD3yM14@L~+_?jJyPak8W-dt4q;4Zh3C#uSc{b^lB(bg3{FueQ*&+JfLpFHV
zrlL%dgCZSs-apDj?9~mxYCesZ(%?c>aF7N)58RI%MeMt;uaCr&w!2PUK}$->kafRl
zXxPrRb7ys!@WLgNRNBOYki`4(tha0Chh84AwXcr9>m@@YGLw}sg>q`yocVM2LFdm4
zdyonix>UXcro(A$lX7{f=?FgUv@VR9>e;h@=UbuMDx#29>d#K7+W~<g%xWb)w+ALf
z53kjuLs3N2iR9RejfUMq;#6=kL2u#9Ey8GsXULGT=GumWAkc~Y9Xfi9Ql!j3MV@1I
z6tjcxne$30|F8cvjFH~_#~)$&(+tbn#yqGBu^^NC)kwvn82Uxd590`k(u`*?`>F$W
zW8x__HD4VanUPcE6_ndo;2Vj+Kc(U>5Tl>0EEBWudrGpRU_m?w52^vK#8sfACF)5a
zg81Tt3%;ZJ?)p9SUq8?<iz+LV%bm#lf{~`WOgk37e@|3WGQG%cJ%`h@aU7v}WI*)I
zTHm;nHp~$NxK7Y-b@-_@TRapm{*zS=#8wz%G(-as*Xfo3dZYb${<shrMWfMDKuFQ2
zA?Q20W<3Nd>_zj+X`R7NqLCc+nCEgCaxj2|FRQ9l&=FsN+acTLPXg8_PMtCv{ZZ$6
z|2}WI0Kzt9QnNWAPn=W~)wq=f<=~d^zRr?Ze}De0OW1d@^K+E2y<9p21r!ymv`-5<
zq29Gt_qb7r3#h~hf4XL^1}}oHri2u}I%=^Ua5xBfci`mgP{?c*k!wmBKq&;;6B8xu
z_V$VrfqY)jEr`yS-rQQIm2&B^#~OCnm1;#LB_;HJRJsjFpT2%A?F``n##B;7&P$PN
zKhF_45`{z!Fqutq4&mE$t+?jm;u5Qq`HI0#1sF-n9)0inrl3GI`>HwF_cooMa_PF%
zdleXJENEFYK_$!<3oGkXbch4zijBPG&}@*jwv+SU_jg)E6-mM740>YTqM+xIDZ4uT
z>eZ{^qCFv}X;70ctT3WgWn8&1J>Bo>$3aw1C~Q}M{U&f>g16))$0LHT4^kV({`lh$
zBm;AxD|Eh&_0*rKD1rI`>7}4A81R4l^`A%Nf)8u*sMAw|>?Yg&^ledk9h{uvP>U7?
zJ0X{41}Q1as`W4UdCxcUX&titho;LJLJ!*w59*ZPl_n7KM4Tr$1H2WBZViDp7PV&M
zgq{J+3LGlnWajgS9mZ<``V;2lcNrQ|$Q)Gcf3CGX5jp2-Lys&lZ_d#KolLXpxHG3Q
zgtX5$FiAOIxIDYxk58L;8VXn(d3`xUXS1Dvs}!)4IAT!1+$9BO9Rc$p@0&DC4}l%g
zB4C7V(v-#OOmP@8`gcMf?Y|-lY4fdzuf2ruan;@3ofHwAuBi0hs|;eIw`$9Q<N7Y+
zkxge`0JNngE`Vs}Yynis=tXJNJ|uhQ46jxGi#+6hSF<G_%E-><KJ=@MU2r}{?R|(H
zI^X#s>CKxqMf>omn?lBb3Y}7F!SZh3N<_bX&e_cl;Xpuxvpz5i@X<+ZY6SpW_(0o9
zM~CR_n;?gqVVK$5j~xwh8n5_>gnmOUbQ$#@_6{v2lcK-(hH<7eApp!ZP+AJDOx@hF
zFu6Y`Cug|Prp)B)Yd7>|*e|rU{(gZX$!ms&hAfVkrrYQB4er`8*r2y}N9R~>PROoz
zysQ7K271hzt_kJ%9jv9SUbnf64-jkJHUihXD<T8M>|#0gqIn_rKo0RVHu9==AZr$J
zHzMa))Aw)RRB-TxIw~u$e%(5Bt;qS#Lw+VRNzN`Wa;97qorfC4Oy?GnaZCgpro&Vv
z47{+zVB1mqR9-%Q{qq4&o?Ms|JA7CN?FQLpB@p4TR$hMovr5e$^&qq|9Fez&qVBbw
z&$@9cZ`_<sn7I{uZMyy*b{%f8%!j6&J2hAmDYjC^A%wG~ecs2?($a(48Q{Q2Cp+{l
z%R}85zm`y;3OtU;3E#=D|1E&TwE@0;IkFeDvCSQ-=}lJIA++)s3^w;q=X?%^xJ<+_
z>n5V;soAwj7fw+t0RC6x1o?p(!;PcTfUGat_dgWxQ-B(yq^yh#TMNr(8w?uJh~1a7
zRK;rw-u5DJ|8+gul4WN5M({covGs<+<m?8-TRZH)>|UHjsgf1QjX+<gR^W8fiecxr
z$EP;1vc?nb3L7<z(H8LdaTv&*=9Mc~K$$*6FTGq_2K5e|G=-!4nSJwTVE)Tvhy{ir
zfuc?my7u$y{C?ek%Bqon?JFPSW#c$&K!A2P@P5sLHHQ_>e-B2a7)QC1okMV6DCCGX
z7S-0)UUkNyjje~QLOD!O6aoc}AFeD=K!6#_Vknj;K^1j%b%c#!_n9+hFJW4V3WaeX
zDSvL&*e=Mt#E?l(Pe=PP)TTRRf*(sv{zxWDX++MJ(^S%&@Rz(blE0++`4=VU?Ru9J
z5T8<VDSu$d=dq8CPYuP2akxoW*z8+4?Tg_C%2Q2}<QFqQ8RtA$uUZ8K*=ek=`maSR
zs$MAWf@0+NAp_zPLNgv{p>RViw3Pyag3PjggM;Z{KwX%vN8ah-MvyXrvwpilIQxKD
z?-|@vd2eFAg?5ytKhAvE!59G;6>}JjIQ#U_PP82YOrGqPQ-XW6f?>Sb1C1M==-Ou>
zU6>Y`vuBYUx<y(G4l=N8`N+DzqtrXdj9VhN>$`x=UtaRf`&nD)_f*f)4QI5M-#GBP
zwE9F-eS2>Ivp~~np97Q|-&)(-`PFM_+8<1y9za*(M(5POKH!cmja2t~BG|rv-|2~H
z<u<jWEN>qB?_8+hyZ_iy%A==KtmF;#s{=*klu2oWRFqghXQNYUv6mm|auY}r+6KoC
z&A0Y5CqW}ODqmJ55xp8kY|c0SFEAp!cXGJfrpXyIucD%|UxfftieXUX{8rFDYdHqL
zRN$YpX5@#jN5G(R>K*<nDk_4B8I593;+aHzqSHC;FYO{P^5%@>Ufa=-aV4CL5nL_P
zV(-0$I!xH@Ef;C69Dts4Y3kR&1nOm~RqN4He#~!-REk-7i&ll$E(p`Q-^9SDUb+jK
zDsq_!bl?1q@?;{Fwk<7tDjE*n9}xAA8lb}M<F*f;()!(J9&z9lN=Z^7xg6=ehB3M)
zai+|%a1tIi;mIyD<HnpE97w<r1%p$Cjd|I8zAJ9kT9+e*O_n>ptr~pg-|Q00TX!H2
z%oAP?3$P)^HxAsFQ+YG<{YSu%01NE?A^tM$a}Mkcso(Q+wir6BfIW0+6j>P<AEXCk
z&{0B2b!FmV9yMFryX50Q+xgdaz#>NpK!Hgn4kb0Mpc8fz&>K0v)lGaW*o4S*^n9>p
z&U)1=ogJ)#M)%bqYE=rgBh3pg$Ri{K%V%QPgt)dSh>*+6;eL(uW%r9^oG0JK^$caJ
zHeNFv@K2V8w?ywe=JBDWrG+kMZT(7e=GO)1(K=%-oc|$q7^tP_a~<aUs(DjmJ_6js
ztU@6=_W-eQX@rXjF$2NH)ccwQLRb!4z&$4kkY)o8hVfNI15K<?gC;=+8~8=`UrZln
zAHwcDQd0SGX(K~JPhjM&TfhF_uUIgDzBlp*h!V%8$zem{GC@85trlz(x)h2!1pRF?
z)*RYu0{&5rL!-Y|ki~Z6zz2v9e=lK&j~poJoV8m%I3B74%O#R(AY}>|4Nd|9(`*WR
z$-R2J_=;V9jzeTU2!j)L<~rT09|(R3%OVujVT*@>`0agA<dDO}ClN*!UP9>c4W%L_
zHw9X=Lnj*q7t_AROc{CkS_GI;m^h$>P-$3Ej$?fZk9VCCdo{;ht3fE>>Ig$f7-2N1
z<7}(i<;(H>IvG2t%a<=#0v@hL6cH+L(ceBqb&~Ej%9Qp;NK&S!DLXy9gj_IDqJo&Z
z$G?<7PQUxxB^*_N4Xb9RCw;uVBjV%Z|7_Um5%%K6i*@l#4X$`GGyn+oCLJFGNII3l
z?Z`PU{)l`Jh3<u_0O2_dvg&CX@G#Mla5Ac>v{cEEc_jho003~v6w(N0wHNfn@7{{U
zL(Jb@NmBVH<~aO<quYIx-j0>bpY4aT7X}Z5D0`iqo&Qz#gmhr;BeDeBtp7hhRoQ_I
zQ9g*po{;O`{`J$G>CpyZgEtEy2FnZN4$~g8OZ9cp$Q6fvd{rfWi#Ci?aJ^{kfkGzC
zle0H&P{x1#+ECZLZzVj;sDGrWzm?qfA%1h=-TlwAN%k!RimKzY?^~WwZ*tsvbZe`p
z_bq-lmg8>KCpPR=vgMrWTK;^#qK4t7zdby^F6a8|wDRK<3y(-kd-CVrt6*8WbKcQq
zd;Jem`})^x4-mMpTZr1Rd&p68`{C`5eWGJ7Mptu-f^7OSVMfz9Fj|11VD%m19-GLi
zFUo7ie$^dMVeMkA?WID~570`tD81Ls+~+s^xlM>qy7Ar#Y_b{@0i8Mhbc0z`y~=K&
zD*OgVBksq^lGoojU#22>3rF^pz@=q;dAoa*m_zeLuzIBdyhtA`dPt7ye#|*8433%K
zit<OSOaRxi>PYfp=_KP=X$`O+oD^0?x~$^0+k#Z*$*Uk=Sy{Z~6<oe&Mpha?|N1eT
z178QnX4*Y2@NT?^K(@*wLvkI`Nf%?KFKzaSo0DA94PvDaVX3J5k+)MU3RK))0&&s#
z$!jT%9x=aV>kZrIWb2H*%8;#-;cakBO6o!LtZlN2LYmZlPSV-1CaP|_I_;k<z{*>s
zr6R>+Q~366<4b`=a%O{aqv1l9^dS<gK$<Q}|H$8Q+~mh!NBw)YyaBK$Dy$!tBOL7K
z&~Y?r8`iBOyB=b=OU12a>s4?r9qZi$+gQxH?asY8<`#cmq~c~(MB{v=!Hc6Zn?|tM
zaP+R$<s)oX2x7`GBvWDRslHG+LXM%LgX?JQC*Qk4H){DUWX^q=TKZ~+tKP<*&dzAp
z*~u1w%WC4pT^eBy-IepP(*94M#-sQX*=Y12m@dY?qZ^I(f)AJCQOFZ~AJ>uBhJM+n
zx`S6YD+T<LwH^XVB#<1yk2sqRT$?vstH?KdvMDcmgSNUC9RX};G;OP}>1i5pWo!8u
zCLiY!mG7?OT%LN8yqJss49n7OA{M;ere8`%UN2aK)|ormmyL5E`WKVyh5@H~aKt<s
zv+cZ+yy0t&Klj=+94?1&4%KQjEjrjyhKvNt7>PRo+2CYXFjJ3C)e^q=VeKY0<{MA=
z#mqN=^e2RM0UT7{fF!IC_yi&`r#%e5%&I^@s*IAW1O{ik@nqg@*PyN4yjmjf;eCTC
z>TzmvMB)Pdwnf&62o`AE{4bbdsOK8o^|rlW&&7TMuJ6m7THh=pM?HxcLn0N3Vc<BJ
zE>fPA7-+h9jZv}*PNfp3iyW`Tj(`#$2fj->L!$U7Wa~gtn<(N{0*m<YX{!+x2R~KC
z0y=LaN5-P#;{KVb8ha5T`#v3r0XyX<AIvwvMkIY!!fEt_X=*GkkPP^lGxs@6a2(sQ
zJJRpzL#RLrCm*uz4JwU7%!=fjpljpIXYA2q$3|dI5>RwvCeWT%>YMQPZBBm#@0qZ$
zd9(<Z3mdr$d>Iv5lnnxsdTON(y;N$2`-;8%^u?5~+>x?=-hO_m<#gj%<E6TVEiL+x
zl|vS<*-nnhUuygCSVY(YOn^A@@Pr6UC-Mjhbr2i?8KD<R@M_H8;Qf1EUO0#yjs-x@
z$3nN5C4)AcKRYcy*5aCvb`^@?Rf(pWfJ`mX&CXdYJW7T7RZEl@7M4i7uphK5x78n8
z+7yZiErMwA$cv=2o1uTgi{PS?Tv%{YvQeoLjv2tEq!ZgSI9Of1Z}Gx~mntHt%a<-K
zhmn~A>i?(n+<>3lks}BB@lmOfGH{?>nZ#I|=uF!ab-!uW!`I65QV!IDjdM^j_#XxN
zah?o};1LHo9eiRUkj&V}2h!Jq2uP$VVXZyeF2GDozhRw_semeul$-#wAXg@3GGK}b
zyqdc^mxXT{ATaS!k@+*tBbnDfsbCcsgRki6>5<G%<(15B*-s^%wGIX)oYrH;N5)xV
zYR~#pm6T`^aV301Pn>u~MeCY<{rxXV86{~veaM4d%&`|8Nu92vsGy+mINRvR&%syq
z_Tz{V+;>6_;^n?$*MbflIKZL%%&x=>B#dLPgv4~(JKcu-7rJxbu^+F%=`fBW1Bdny
zgg<0xNN`x1HKtDAs~2AJS3onE#iF}oYv<pX<o+?XHc)J>(Z!31eozsesAb@kY~j(^
zu32wxRhf!ez8KrxV;UCv-Lt;xyE!?*$)jZt+4x;^ymk$MG5??23gBNG6&Y!Qytx+M
zE|>f6_4%YOYzudVfN*lO2~r!Nq)MK%b#J0tLSVt6?w<P%7~5wabwFOSG%P(<U(=0|
zW~3wSlTwyAMrt4A_#PaCuR;C1xcS|x*|xT}jEEXQa4HR{h~D9Ah)zM6Vw;drHx@)J
zlZRTL>y%EWsrDg{>F-%W!DV-yO2UIAL^KoB$kRYbpQxeh#^LY!V_rPu94G#V%uNm0
z)ex&b04zrgQe+N#bwA-=>(Wv#eSUuUI}uMEM@*@&@_F-K%uQ!z0QXut9)*GKOX5t3
zA(Jy8F(|=U4Hb5?8Al<lp#E`Ew*sYuZW>6XAw@+5L>kd{+P8?GdrcXim>>}ra&X^=
zpnhc86!8odU?CO6Ac%=_TAw+ynVKsL_UY&zrxOPniv%3m?o0Qp&}R}(YKT-P%{oDE
z0#hfJ>C3;1(XoXg&QIp!q%re^J=~9YwK&WNQFbQ<?O@{7!f1M?XM+Mrk`fT&{<?XS
z#5$2|RYL5XXcA!IPd{a_q?$ETjp_|kTKwIMUm9j3U{-j~%TLv&*->d-_Wk)c#BF+Y
zPeNkDNf*r*IG+eRi;;a<j|Vnd*mPNc9ge<LPmK=|v4~Wd&!0b&>?TS$jtN^%9*{G}
z6JkQ)@tHv!CDTZb_P`z`GW=FC+ZVX5XaAX0y{N#Q*U@-WuQIf7_{NJIafmB%E82H#
zY3QK~9&0H(SY}p+#RTtUMZO5PEIHA&>tATc0DyYrlX!m@R3_x?^Gsbun2yfZPlDBg
zw{T|Cj{{4EcsD@ys!)N@lm^)@Bx&Hpch(zjra|Vp3Y{e*Bjd0+go(2v*NY63G?u^O
zAmxNB4c&9k8UL?6>&QP}o1-_PV^mkqar1_K)xU}2o8R1A#4wgKJQFAv(r76B%P!0u
zc?wS9dDMVMgm9dFCPqR#m${hC+10Ikerw^qO(Sns2wZ}TNTYic=nzlXX*8ZJY@&!r
z&5nDaap<Zt@y-SlYy+@iBIRIUcNgrddTDSBP1Ttw%N*U%tPqz7BF-WXl9{3>5jh=E
zb6p*h)}(BZ!298S`8?b%!Hv+7+|xsf=zOJ>#=m~Hl9Vv1?@+Z!RVSYCiaAgCd8tZJ
z@pTkh0Hv+sSK}-9`I8eN<zJF67;g4}ub_H|g~<vA01Zhl7U`eZ3-2F_{AhqON6wJI
zA#_(@8t5COa0yu0+=|a{9hR`np;bd-=alhQaCCIssX|~GrO*pt0y_>n2kGp9ZKDq!
zJWvHyJbLu#@~}B$*#%P*By5HO5CVO;T`M;g0NU62%>H7MMpcf((9!t+;s%oFIG=<-
zxgEJBxO=;UN{yr}lIv3Jdeug{D^DTz`vh}@8PHYV#~dbuC`Sg<5_TNElsoiEoGfI-
zT?FE)WAT(CP2P==A-KfF8zh|$nO1QD7``u@^8-HvDRWUV#pHP!BM?e@A+td@MI+zD
zIsrjIna~`f_1A77$|I%lMmIdERPzQV0>LpNyRWb3G0#;Hfsx1nfByNVaBg%z8y8Fa
z<KKV%WO`+b-eOkBXHb^Uh5jjx-X*^GM{!3qKuu2KV1zN$G<Y|HUiCk$VUBIzYeP3H
zga(+3e5Xk^%f@@{538B>Sl?Ux3Sk;rL}+N}VRQ1qH~#7zl)e^zko;Zx?{jkz2rK2e
z10z<-QI7kaQL6a$a<~wc2Tc}ZokXF>i60@*h!bjYsyOm|BiMOV6SXnxg%<f3uKF{=
z$9{od#$l8K4?9=~Um%PJamF~Tm~QB+L>@$C<Uoy_<M11tv1D+R-<Jc9cTt!#wmq2;
zpjM)5fEa(k5`tb_gF2(5IJZ$8qO=Y;VkJ_^<AYf1NnGe&;qxOm7n{7j^9L;g&&x6;
zQWnG%C|7<*6PYrXr<ii-+TBo?U`ykO{%Qssv_~9v{mo6yHJLWX)C$bcibQGVZJfjk
zgpq}#*BVMd$IvQOV09wtP}i*Y>LL~SYZ+7&cir9O)f-me4)BRYdB#G{HOFZ$S_I7S
z&h8K&A5JJHN8^x&2E1R7a)gVMp=}h<<E4^lE7&h;QWXgM?K~iU@)4&`pAM^?TRv`J
zTir;S;8a8eA^%v*C^=}^x7$ESz~K%J;}lRjM-196oontc592Pu7!<K1lo8KIaxWhA
zrs)0qQzUf;mw<HwDbM2Wk2}dFeeLi!^?(rKGHEU`@OC}%-U&CsNw``A!7bF{j~`Xw
z#o#o<b6i8l3noRyB$J>6;wB`?llMLshh5%nv)pk01o=dTDSy)<F7mg~pZ?Y!<pDT=
z3qM{RXVvbZ%5T5+b>2wV=Yr}v^7+^>R{9sr%`TYFe%oDs88`#OuYM1R9fO`KLqomA
zHc7=^CMoFu-Xq_ZrW}W44uFoc%!w=qc!YMdRm3756iA*40&p&yUfxSq|BY|2Ros4J
z_0b|wb`PbvPBPMI5y28pB<4r-qF~n<2he>imW_@~N~*w$exR3kT@!IQZsn-^$0ku)
zP<}RS*<xbpgks7`T>>OrwUx<sGQjPous3k#>U;TBXo(2*pG9~Q#-eYo1i&mFsf3B+
z`f-5yat*wEcx+4^7AwM@Kg^Myq;UvaG=Ay!ms-NilDsa3(D3ouyeSkJhIxz2WCHdB
zfOcQG2q)(Wf;-77sbR)L3f*J$#0S10dk=i#I6YFE>N@M9n{$mkBZmg;N#e}6^ROmy
zv?WfhbkUqR^%=^+ms}@%5*A1Iu6};v9>x#fLiAxgIq7yD1g@)MHq5Wc5XB0|h6m!W
zK%56)Op<H?1QQ7FW19ee?Rn$Af(Rm55#OJiGH>&epz0294g@2Jpz8?pbcpdCWR18c
zYvV{qx$*7&|Fy`S4LT^t49$RQ*Q3ZGG5q6UHBl=meQzS&$^l#H*?rbaZ=t;Tmd%9<
zZfJMDlJ=j>x`XTMFkyD!4Tt>}y@B~X6;)5(N?CMM&XD~1TJHD50sr%7=8r9JdPN~Z
zljm)*L5qWw{;KZs_-LvIF9~7pRAbiU!kcL6ZADMWv0{S%Jq#LO&N6bMm<r9gSJJ=0
zyiL*5Xc5>$-FcIJ%6QJ*VF@|af69c67D%u+x)Ek-q$9|(xZvg~R_0iR`g30)51641
z7xN^pUCjL1jR2&nQR{zi!vD%fl~x#$DhMOqj~;#fk8Gs6gB8F5GblOUw*KEh3R8r|
zb%?}FP=r-c&*J7{apy}^$`Elva@ux$(2)4kh|#1X*8$Pb&(ako6*eBrd3Q2s3Wu>F
zjEs%VVD^AY`EY<`%mrTdx9rdHXF@XzwDwl?=M-dSs7hEYRatgsmHGZI2#bO;*4s_q
z-zIWaUSdQg_$mlAR3a1T5J)3G#xe!EPCzcPxAiuAUZ3b1Hn9jqo(SY7-VP#<)oJG1
ztDssL7JC=jKjop53i<l!8J`qVOL3`x-&|sb>QCqI^j)}Q2?5Y&z0kBeOpvWm$ak40
zo-Y6+5?0DUVdRtw@$1kt!0Yv_9rI9bOu@7<?TG0C^`zPkwo#pD#yg2)mN(JEL#qFV
zIliKY?Eu$_C`&lWprc#NXNJfZ)Z}MDeNs4U#HdR?g^cV3o|i_#W7G=NFkyru@FbdO
zQ`ooAD?0b_LoY)@fmUi%iHbe~rh$BkGF-2%cy1V}_~7Xc1*vg~%sb6FlUi~K)f@J5
zA_#p}miK&OVDjl?DA0)UP<JzcBNZfR!IIV99MQ6h#t4a%=MP#o>j>oidhRT0jyjIw
z7jfeTg~WUz9NCTwlXd1F1VHw0!BHs`iI^RjAe673V5hz!n<)e$ygAqoUsFJ4VD)=2
z$X(PPFvH+0XnQ?~@p5!SqO<?+=lxHqvhmffQxB1rm2sXJ{`_d?F&s^tI)!5pL6v#f
zoyie#{kpbMI+@nXSFEt<;-Nx=O1<3<jwZ?$)R2c_=J%Uffye<lYm=NDo~|c^G^u$@
zo-P;=oxeAV6%RHe=huLoaejC)iSJ`WRe(Jtpab2`1DBzB_wN>>sYJ@KkRzshhVBo6
z+`#C0`mm(wOFJ?>n0)?R=4Q1K1pWsgNtzvkD}dv5zS|xqY4C#nC>-&%)7`mqC-G-V
z!@{!AM0qDxB_ivgfP&<aX`oFc`f{25iMKaLcaL?+RNHphvuD%N+w;8k@7uSprBqwS
zkDrf;0kDyg5Nvy8)@-7ur{?alc*BRxd9Tl8)Xt+UzZWw<%wRK}ztvaNDgPWSPCPm&
z5e6wa{u3x}PbX2vN!mxGhN<etO@pYfpr-Qj>FG_y8D^8&J#*4YDU?tILGdvUdmz=5
z5D6ZhiN`=ZKuE}&1ETxs3Ohe_1X7tY1j9W2Kwtd~J*(rHQL-V={?DnhcgD4yDDEH*
z8;CG$^%&<Kic3ngF4dyOU&bRl;$$<z(cSy-e4S}f<Wb{+h`7YsM>CdNq6IVGTTjZ&
zrbh@uz3?zNr28fy`)wseSd7}gN4rq5PpJfl3!JnOB;laK94xli>5F5xp46KxI~XK~
zWnm}QhgqVLrvlzK45nxNo+>*M9sqj6p?`?$ndX^^!CYWWx#XdCv<Pq|F}C%H<0FoF
zJCBCPo}3_>AT7md%p&@NO+zAEXY8D$A)>ta4Y5W6lYwkV*d>xg%~rpM0Y&nou+nN;
z$Ay!}asG?p_7dH6bQEd?f=selT}bLW1z#Zro`XD_wao0#83f8@X)sp3jdh?VAqmV!
z9rY{B9{fEkwr)SMJP|g_1!on5a9q6a{^4w|#fuknBa23AF&;zJ^IRtJ(+s{^4Mz#C
zTq*--M2iEJ<D}x~>XK?u#K{48T~G&PX+lOHH$OXc<&Deb0*_TB-NMnG*%@47Q;JhF
z1or}IkkiDMT;G#(pwFK_Cx#smX)JWj)!%il%t>`d`_By1Zv!sIfm&lvV3DXGMoKmu
zN<Mjp>uP5b5&~exGcdN3qhdNr{U}$}@QJDFErsMEZm6};_`ir;g5VT@$BOp7RJ><9
zQoS0)08g!&yqKzm@#Diy*N1%X#iE2R!x+vYt{P+&h~$JJA#B}?emjSX?_hg<9bPm{
z&**q|F-rI3<O9tYE49;P&E_fO{JN$o+?lY4GpU4&k|CJhY-s!GsVJ@-4<U&b#+Xpm
z?R#uHP|F^3OivA!xvRB=z^J1_S*`^@h{vt=;$#MCv=9;iVZw=fPENp9mVNE*jl(lq
z&3-G+zfU1yQeQxE9yJX7WZPAK1Y5Y~{uV*9q!3>}gK~l6uT9J+6fRjJ&erKUx4;B|
z&1V>vuF5((Pw{lpOD(q|(P4qEm4de%rIPg9;lqc~sDj_{v+%!Oxf62YmZOv#D!&A8
zMLBx>gfc^jb-}}@wE&tpDsX>3eK~2)o_qdRd*>Nd)w$;JV-jO-Y$<5$6}>71TM#Q4
zR1^yuu_4V42x6g$NHI|`UJS_rL4$Bq6hstkNE0v;6f2@ADkyptQEEg=;0WB`b7E%A
znz{GW+*$Kw^2HU_fqnMgZ+V`7d(GP#qY!)GbZ%mJ&e&iC7a<{9HrqASVG=yZNmxh`
z__(^(c2u{pEs1*{gsXjqrX?QYProBtKx$y_)i$XZ(pgNiG{a)T+wlh*uQi-~PugEt
z710PF6r4jXx^ZkI7p%@un@NT+Sl_}_SBFV;`R01Zx@x}N81r=Z0mzupZ`>9WV~}Cf
z3<&R&Mst715>&>NuD9zz7lAZsRb+on!CtuPm^={@F(oHh+={FKK%eNfF9-EyrHY25
zr^Ttu{=)X<W3OsAw-mY5yj9dpBNj9G#VH`MvUoA_xFzvAF-Z_lO+^Q{!R>p^r=RZ|
z^~npy{yFN5$}$c3aA3)(N17xa#pI{&G84n!WhVarznY8(zyGu6Ae<8K&ET^hJp{H(
z-q!w$`Bv7(2L(*zzap*C+vz%UHoL!FL7+%VY6nI3&Y+|iL(dawao09<7s7G~sQj6b
z<=5QZx+~^6om{2y5EW_tVaoX*{~Hn$*M4%|X&BfW`$kWPhFA<UG;GoFqqOSwzdiY7
zn8j%*1!+z;wBOtR*Ewp|qPt1!Z3P|`=R9gVEwqfU?!?3a8zbOy{bQgyx7qfIK?#5(
zX^%;ROeMKhEN%jR0tuLlD;Hl>v%0v|ed8W^6wYns7wAYAAqy3$6iQ-XvKdP8XHfcx
zCm6{3F7gH|tD*dYU--0szjkb9V-p#pb}Va<=MTc#H59o7X%l*McgND6^0~t4d`?1S
z0V-?i>lZQABI+I3Ewvp`kL<AMAs@>0vo_f{1!gQnn=H?70PfAyG&0!-*KaI+cEfkP
zqDr?)#~`5kFBc+SR5f&IXsJyeiojEO_`-z?Th-6|T&uMF<ox;L@K8fezA4@{*QUIR
z_pP;ZO-jMOPaA9%ZLjpM&eZLm-4R*wjQJU7z9Xlkvhvm!a_z=XKiW7&Qb@GJZ-lN_
z;l~ch;OC0#L6dj(Ox;&<z~IbrdFy^DpYTC|ykKo?N`s3nF7Dmi?LU1KOgkQRr+D$u
zr)E2-V5Vj$A!HZqJtCv<_x2xcPwtPZ2J7<DKiG%MQBhGsznjj-NceH023Sktvf-mB
z8(B(G-Oq+z^95Gbe#K(mW89|07%OU%GMnenez<QuB45-wG&`sHMxW$ukfmja3x8VP
zO^7P~lQ24QTY5Zl3zJ%N)at9rsTzf+!S|DQTAn5&9%+qb=G&UTK`<<26DBd|Yf=0l
z*7<YXy-S{m-u&mJ`8SPy=FsGyXxAo8n>y7V)pb0!yLo|K5>*D&>kFw|@ywP@`0KMw
zg`%gUoDonqf7y!2cs+J6C6$?sWuhX=$U<D#&_=QM8fdpjAW%0C)78Cxw?whSpS>`-
zEqxcg<j>Twtzk{P*3}fY@&nu(G-AC!$7_>Tl{$-@D!##Bu^h53bg08bOd-g$A2Du?
zM#iQ=0km{P%`bZrh}UAe>II;ub+qv$X<R;N3w}nXeZt6<myU8165uB|KP6vzacfHw
z<a5pb2{=J$YkqQdv#{qTvsCx*-w!WyIdLs)IDtrp^C)9QK`vCeBt1|hgoK8M#`tr~
z>J;r)6l3#{)Bxlk+`023nO9U|^0eqWLaQ5GYhQlD^OP8KilFqw;oT=6Om=@in11Rd
zJKq9yD#Ud57K4fsdw4u`$T0dWYLEqV{bEjv1N@UDafsh1wMDZ+b-&?{<292^ei4#m
zb5CYa6NCHnxLW-VQ^W`(-cPQ73~XJjOv0E^Ar;q`s__q!9GW2IBK*TPD$MAdoEZe6
zdzh)e$hW&ODKc%rSrYd<HB`PGvkJ@pSsS0m)ztGd*>%OXe+WlcNu#IB==kRDr$qjZ
zDTQgVfYJbHEtbFgK;6g4$BH~>vFOO-*0W9}rg5QJZn=~BKFS((Ym$_cu0??F?-YMb
ziZ`J~op*H&4Sa9N7$Hcc#DMUla9E5j>W5zA4xxy%7QHHSX!zf<2bhY^&mX@p&;d-o
zEK_J|@m1ad2^0T?tl$iYvnnI>(SW_;u7GPHkjgutT>bm+MGI6`qELwRe9>JXeHJ<T
zSL|u>LAfB;c0`fFX$Y=Oo<`(%OV1`)B1D*O9Ek&Ec~Jq<&Os8zp;0uu4Aj0vi4AD_
z9$kx?u9*&s9RleIVoqyC%x(N<gJ#|jlJ1@NA98oC9HT&_*)fzP9G4*S7eQuZWnh_~
zFewSr1Y<d=xJFE&*?gY@E>(FM&t9FRSa3!|h&B+3C>_AsLo%A{Em7bsHIJU1hdz13
zER`6F3G^+H?0eC;z>-p|D&4D!Vj0Y9*?VMYW$pd8={RVoARF%@Fi-<uL#k*PPh^ef
zO$nU9rR73FF8+0H2A1_8wwf|brBF^4UwZdV5f_fArzOgeqXek4#iUYKU2H4a60oBm
zcIehmX#8VNW5PT2H9SrbF)WQGO@8WAeT0UD3suK5_GB@rN^h`X%H<sNC+9{QAI2A0
zXu~@1u3G&+RA_C47t=>6x0^fa&K5RW85~?GxW>x-1l!_|I(If`VKaSLNI?5;o>@=2
zpG{-M^z@pwp$E9YNI_KxvPeAro#kLR-ufv1WaB-T(cX;LRScl3@>c{`A2?`GwvX=M
z!Ixe>I1}?}pFYl0r%f9dIDxq#|I>P2nC_n<BGz^DU%qPfYMck%P3X-wGN*cCDlwTo
zdv>HFaZTNrCSS={rT{Oo9H=O`nw})w)aH^sivw|dX8GuT`Q?of9kO=r-mQ;5?bU|P
zBMI%<RI+R2>Z@7<Cr&KtHe%W2NEcuH-t{g?P7iM1C&4w+rKkV$^EFp>OwgC-@q=ez
zQT6rgn$K9hM#%MWftRL)+2jJO1Oi<3<RvA&X8kMh={&ka)_oYs=EuqQc>@AAwr#d>
z$*hK&Ewxl98m$)t4X94Gk5l%pE+#BH+|Kg-6FqC9GdpLE=v7rt4={pGucD4n+gtLu
z=tS4xo4dK0jxvx@oi!r<aRZFzLizgkEJax!4&D5lz4nb-Ju}jgV3GjM*QW7Sd-Nd5
zqqXrj-p}LPc9Zk6DdMwD1oJZ6e-zBit59V7t%doZidRQ;@GAam<Yr^A#EoME03Tak
z2l*Za93AiTHrWRV{k>Q>98|JI2nn^=#xwir`X~gN$Hf=JnHc#@F!6!Ll*&tu^l5VN
z+-#M;$MVD?#5jz6+n|XxJK-)2inj*a6(P(KfEDQR&eQcf+Uzx_^Ag5n?DZGwrly%n
z1p9}1y5ozcXkW?AohyDVB$0<8_9k3!vesdcgVeYz8T_+X73;7g-4}w>+iWGW_Ive(
zo$J`w(2D227?dHSrKvo;WulmOs4WB#AjjyAPv_vnlIp}C3fAWG*Ops-?Q_qPFf@HR
zX8>DO{W(&679g`d!1o5DceN}<gq4U0$;tNhQ<`AkmNzP8{LLSmH~|KwQ)0rHQ%g^5
zX)Fm7O(N^pD^v;w-Y3L>jB)E8MXaFCbd<mZ<#h7&SP}A^i|+AyB<?rc1le&!%Z8x9
zz<hc@H`LIgXkeX6>dRRPnG!tHo4r8j4sjp7A}m39m~v*kZqIac4G1Y|Gf05|d&&wD
z5@bzc!88kNgBwi0_zexZH9MZ9K?w^#_U*+zX;$>;RlX$y6+^W7__=o5-#S5NvOEVv
z-yh)>-&d`iz+%WlfM&}FXPo#9X*pTCoyScoWy6Cdfh9|TB8l<tv*l&~6SkQ);>F`^
z2A8bdO$>_4;!ImO?;H<PHFHSFQyh6ZpuK4Abbia-5|@hgyw*1uhEO25@stniR1LX!
zWW?yeNektiU9cfpHETY0mM&epMoTUe>qq}&+n~E^WdloKjd{soH|FeZKt#v*GU9Dc
zT4=Ou@O%CJR*3uCtnj<<zUx9YL?u%A{&F55nXY%sozD+2WjFIUe^cZo(fTB?*kokB
z<QvYKpD}uSqqmKzU|*6~K}wZ1#O%4&O~`!{VADYSbc$^+QJmGaShljQ)Y88=qUkA^
zG~K7+G?06VS7%XRYCB+q*g}TW{(8##pF&!_hh@4TR8sr4R{J+6bll#y(PI5V%7Xpp
z+O=ypD|Kmk<xv*)JM~nwFWD200as)cOxpPOU%y=cSy!F_I<leEHNt3RugK%h!|m!i
z>@tvh9oW$B)M)V7)UA!Dn*(YYBa-}u98`WmN(;Dy%F%%&*&P(IoI3DnM2Nb5h^w1_
zjR`)Lh;zmEqxV8Hi#@RkPNqU58Wns5%B*o)XRS{QoCmzI1Kx-iYaXvqXa>P*P%KpR
z+!okFe<qLMT7!*yx_U-c`Y=7cD*xe*xz&bscF;)5!=Uh$kJ1{r??>xW`Wcm<xLWNS
zT=XEV=<?@P`JOHYQ`7QZ7p6F~LqQ)({sWV8Az%D_iOT_dVikvs;cbUhpDMDOxk=Tq
zguIf&ahc1;7WPi)x8_3^YxS%vP?I0)?qxl)5QGJ;!Hv~skDm3zmJ|!UkF~tPP3jka
zwUxPYjPfhe(6_`U)GL9iFQnO`B6C>7e%^%edd^#{zV=<@fxhWPn9UXmE+QXo9w(#7
zgG>MIV*7Z#jyrZjqG|PPOz*5i&O+F5+fZ%EcTukL&4_{#HoII=n3U__RaJb^CU<w!
z2M9fJ*(>8S3{D;Rpl#b%SVD#HU^$T8T^KJBpi)S*uSivVJl)v%Tj^ZDk7C+j6f7UU
zE>KWHQ;&MXE`9otx%B<_DX%Q1#Xd2LOB0I#i*yuVFbCV1gF!Vt51uPD&*CtD<Ei~V
znCG;Wy^d6yoIB7ss#&Q`$EP~?yKe1H3Q^<4W&pZl0Du$HO{$c)%bN$Vbp!AB1EHPu
zMF<08MrzZe=T&3b@(L!@_v)x9xRPEV+u5r#D@Ac+Y<zK@%BaCG5yvbI<co8;E+<&X
zkD@-3ARPo*n#Xz1F=3<5*NH<oQbR@As)xu#3Lkjg0u~s}qqg;V@bvYETI&&BWSbx$
zVDf4fqC(81F;b%|#lEesu&%oPgmlv*gnW3lvf4XBS9KcxW9A~9dcX?i!fF>*jpnoB
zX<%iMH%x+H?;q^etXT`gBQj{N=$(}tsglhA2vo9d6QSz_=!5@H@-|ew_~zJxp%ie4
z!e$B5Fy%)Js>;Va%dOR`4WbZ95#SaMah(rxLE!VixhmO}@Dm}1e>6ws0Yi9t=?M|_
z%c(U1r5_xLYp4Md6{p;(q%O5~dsY>n%zjX+>r6huAsJ~5P?3-ED+5fo;A*+c$vafE
z4{Tev{XNL;qc&PSWlt1=m^9lIcDKMMD|_~zSd%jl?`c?iHJG$?-ePN&EleD}Xn)0A
zL-o$mb&qx7jaAg_eWTX0sfj3p_Y@1wS6})WIK}Z>w{C@(VWT`Gq+`yH{l!-UfjdFw
zqDVVX`ym9T^3=wDX`0j=f$#?Dh&4%~i&$Dkh*hoUrq~rJK0!I~OAc29+ZCCilo6a<
zk|4qa7Akbhjq6mtq#rb~gi2zC$dp7aK-o(<get1L+Qo}#;1_dLZzyW-3Wr5FKpEXv
z0k&B&FjHp8{G%Bj)gi0T{Ey4exR>RdLh9w)sl21*!fb2slaf<HRpnk-svjkbD7=Df
z&X8~wl__U-um#>@;uGuLAXvZNajhNO=(4j-*g+6f4q##U(-TE0ScjU}k~?<ae2!e?
zhjMsQKCCQAziiV?K(YA}vatElqnA>40XlK|(gJC*-+9ghN{$)aiQ&<sK-~fTAObgO
zp4xTpBO+>P_t<sUQsLCpzIF8VD1b;&-}G=A{Jz$3)CPIHMKQNX)-s~AVF+>gBb;G#
zJ@fp;A|x)-x=>2UZhd8KqA(T039)9!fFqQV?zgEaKEIr8^>5-9GW2db%KMQxERGTw
z%+zE+I9%U5Qj|*veeOv?#L!+W_!^pYtcMa@dH!jqxM_2$Y>g>|#I)_1k;ETyKyaiy
zOq1Dst~hq*p{x}}RT;?&zX4B?(MeVk4T_kf)h>cEU;pI2$s?0^zNU-ArhE$9e<2ZA
zW?rB?Mr7BaIL0v_RhDf6rn+)6wu3@ziX_W0HYL#w(Ca8gjI>g5*U%meMxp4p!XEgI
z_SM|p{wN*jQINe<2{Bq`>@-ZHhH&1+MB>{2UH$N1)e!&e|1Wfuxx_Jn)bJeF<mNU`
z;Wy#eI~q|&(GPM;9R3z@SF;sbV|&pu<sP|x2eC2JkkK-V!R0{CKf}`JT>y}fRvtNz
z#tdh7lgc(iY^B0qqX<LZ-u&Fv3HplY5IL0YCAh^cz>}jQx@2IR8EmGi$#YCdkLIUK
z1j%79%%`DwM^dCXM-ciT`bJS8VLG#w@uZV*{t(EHwMP;3k9-3*i>>O4`=_!phR*R}
zE7G^S*-Nk^_T#e!w-CV!z=mfy#I^3hFCaGR`FZSm4{~o@GEi)AypP1u&v?a|2Xv7}
zm5<XcnG=Hf(p`##NlXnin|FvHt9Eswc4KBnV?0Jf89Vj+&pexsV?jiqxd?hg(+R+N
zfF#~#N}Pqx5WgQU-6ZmqOcx{#IPJ7eNrYWUzZj}(afqF&Y`4MV<nM~7+VGKlm)uD)
z5_P78Rno#34CgClsK|{NVNLawI@FsSuO_l`F2!SAz|8A?(=Kso`?EF}Oav>`Qqn>X
z!9yoAf$Ca<!1<$VCCz~#9tz}WArR?GJumSx7Sc+{3l|lnXhVVVKtMuV_2;o2&EzTs
zMrd9W`>GBa8p$e>XcYcr8M2zY#HZsiG*YJ|us4v7haN)Gf+QO#Ru)h|9nlQ5)Ft@7
zN-VI^Iayu8q9Br4J==`qa&#WUMtGx{Awv$*#!46l6IXB-?N~azviql^7;W#c1*77A
z9Tmxjz($IBGf<?~K6FeV5?vKSj-z%g;6+oeZ%Y&%@GK>6#0pm@Ab>SD_s0hG*)jvb
zM|qe+rqJ$Vqu-yr|G;UCY!=+dBCa>cI>G^fJ%SGp#S{b+Y7cqdskDVPQx<q0jR^56
znfIXB(T?S{iqE^bxcx;4&v*6PQW5hqneAJxkfCwHo18;f3s>;Pl8%Ze@qfG>ZduMc
z%ehm9vlNRc$EtCF9wMf%=Bj8FY}pIkwmfDtl)X{;)v^nUm}{mKTyb&_N|EXWtkl@u
zz>0r)wdpp!#H7aO!3Apjq%ZaL7t#czYdgSQfI%B?vudY!(hI=Y&-gYl*;c!UsH61e
z=Elw4)NAa9ez~s^m^}A-Op8W~ZF(DAFl>D$YpSVIB+21728*Cja&ELufrI8|tW5Bz
zNFWu=FFlkRwrh^QLeVHe;`3&(WQSFcgwmvpU8*D}_sGP{E-IDF;QsxeM#ul;rHf)c
z!*e$ME<2|4mWqhbG?$~=6g07u<J%~5`f9#o&Em+cv^!~Q#>XA$r~3Q@#oo^~Kc+`Z
z*&2jqP11Ul@XT9hm8QGb|F)%IXHZa>w#b_yD};=g>~;VA<NHjTQZHSPttKWW8Qu(%
z{pSMw{U5fDBX_j;H7eS#`+cA|@MFcp#A_|bi&aef!VK3lV5dp0kAau2WIZbjss$V>
zDO}HES00vC!|Vtz6e&P8<x}w~YQx-yB~@|5Hx>7Pc^!ZE-_NG=`}IrVi1$`+w%cU)
z)f=^08-;<1=1MqqOxUb%+=+zLB!OhAazT_yN3Y3g7UCx48iPz#-u3&a&}wSO(T$;*
z(J|dpaq4ofA0|;SDG$?O%l7Gc$tKlxXl~rF_&t`@aHMir)r8)eY)dgKXEA$Z`%}v1
zTJC?<=uJaIn5$dZLOhU?kv4CJqzZ|uZ0XsYjPo@z2Vpb3-JNNUlH95Q=W>umu!`UI
zYx90ZLVOOo1s3tc2(Bangg5n#B+OlEdDgd8GL&#6#NrrY=B}%^NP=;hCPcHDnOR1G
zGq|Gnl)ZvKG$Ad9JptG_yYg};yl6HaUDtC(G2pVEiW)|2+$hkM@p?xlar2Ul=1pPT
z=^1m4)OCO>JKIj}70LQtzjK40);bD+U0IZ3E;?n7syZR=FTOd8;o0i?p{7&(JLFMD
z^u8p<IpH1vJf)y|RIXX9O?IEoyz~oz&zSHVeGGL7XrTDJ{wnQ5$#ez0EH*4$bZF{d
zD6d7{0k}h17d`2CJfHyru};q<+?YvwKf#($l{|kg3oT%`hLT_lpQ*glpxX!C6<_02
zy9uDi==yOD7G^z{tqUE+!^=~rPcMhJ6LgYwenIr??xN>W3JlEZWZR&APl4q^G5O$Y
zG)XMS64@**+dEmIK&A9gqvv)zzYyL)kS)f?a5;q$ijP8`WY`}>A4@viMTc%7hf!~f
zeNfPADXdWJh@FqcPNFn9Mq~3MN6EM5yoKSS*(11|G(*cSoRErzu@0^85N++}sn5#q
z#>LRvNte#fpoF24&JR~hqJ5sRr1F5gJs%MbqW!axZw9+X4B)^JW-Kp(I_HcL;U39`
z!sQHEmNI(#pZluROeg<?5dK%()*sS(zwj0ReiDol3nuzsUHE_H=dGE|<24NUC(qYU
n%31yCh(YYz3Ugz$yCb?(Eom9=7oh4Z-^+BG+0=OBW#9e-Oa6ci

diff --git a/0.4/index.html b/0.4/index.html
index d3f16a9..4e0545b 100644
--- a/0.4/index.html
+++ b/0.4/index.html
@@ -290,5 +290,5 @@ POSSIBILITY OF SUCH DAMAGE.
 
 <!--
 MkDocs version : 1.1.2
-Build Date UTC : 2020-09-18 16:37:41.816764+00:00
+Build Date UTC : 2020-09-21 16:41:28.814785+00:00
 -->
diff --git a/0.4/reports/index.html b/0.4/reports/index.html
index e402585..e1d790c 100644
--- a/0.4/reports/index.html
+++ b/0.4/reports/index.html
@@ -281,7 +281,7 @@ gp.GeoDataFrame(data, geometry=points).plot(ax=ax);
 <td>What year this row corresponds to. This reports includes one row for each year in the simulation.</td>
 </tr>
 <tr>
-<td align="left"><code>product</code></td>
+<td align="left"><code>product name</code></td>
 <td>Product being produced.</td>
 </tr>
 <tr>
diff --git a/0.4/search/search_index.json b/0.4/search/search_index.json
index ee40508..a0d9406 100644
--- a/0.4/search/search_index.json
+++ b/0.4/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"RELOG: Reverse Logistics Optimization RELOG is an open-source supply chain optimization package focusing on reverse logistics and reverse manufacturing. The package uses Mixed-Integer Linear Programming to determine where to build recycling plants, what size should these plants have and which customers should be served by which plants. The package supports custom reverse logistics pipelines, with multiple types of plants, multiple types of product and multiple time periods. Table of Contents Usage Input and Output Data Formats Simplified Solution Reports Optimization Model Source Code https://github.com/ANL-CEEESA/RELOG Authors Alinson S. Xavier, Argonne National Laboratory < axavier@anl.gov > Nwike Iloeje, Argonne National Laboratory < ciloeje@anl.gov > License RELOG: Reverse Logistics Optimization Copyright \u00a9 2020, UChicago Argonne, LLC. All Rights Reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.","title":"Home"},{"location":"#relog-reverse-logistics-optimization","text":"RELOG is an open-source supply chain optimization package focusing on reverse logistics and reverse manufacturing. The package uses Mixed-Integer Linear Programming to determine where to build recycling plants, what size should these plants have and which customers should be served by which plants. The package supports custom reverse logistics pipelines, with multiple types of plants, multiple types of product and multiple time periods.","title":"RELOG: Reverse Logistics Optimization"},{"location":"#table-of-contents","text":"Usage Input and Output Data Formats Simplified Solution Reports Optimization Model","title":"Table of Contents"},{"location":"#source-code","text":"https://github.com/ANL-CEEESA/RELOG","title":"Source Code"},{"location":"#authors","text":"Alinson S. Xavier, Argonne National Laboratory < axavier@anl.gov > Nwike Iloeje, Argonne National Laboratory < ciloeje@anl.gov >","title":"Authors"},{"location":"#license","text":"RELOG: Reverse Logistics Optimization Copyright \u00a9 2020, UChicago Argonne, LLC. All Rights Reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.","title":"License"},{"location":"format/","text":"Input and Output Data Formats In this page, we describe the input and output JSON formats used by RELOG. In addition to these, RELOG can also produce simplified reports in tabular data format. Input Data Format (JSON) RELOG accepts as input a JSON file with three sections: parameters , products and plants . Below, we describe each section in more detail. Parameters The parameters section describes details about the simulation itself. Key Description time horizon (years) Number of years in the simulation. building period (years) List of years in which we are allowed to open new plants. For example, if this parameter is set to [1,2,3] , we can only open plants during the first three years. By default, this equals [1] ; that is, plants can only be opened during the first year. Example { \"parameters\": { \"time horizon (years)\": 2, \"building period (years)\": [1] } } Products The products section describes all products and subproducts in the simulation. The field instance[\"Products\"] is a dictionary mapping the name of the product to a dictionary which describes its characteristics. Each product description contains the following keys: Key Description transportation cost ($/km/tonne) The cost to transport this product. Must be a time series. transportation energy (J/km/tonne) The energy required to transport this product. Must be a time series. Optional. transportation emissions (tonne/km/tonne) A dictionary mapping the name of each greenhouse gas, produced to transport one tonne of this product along one kilometer, to the amount of gas produced (in tonnes). Must be a time series. Optional. initial amounts A dictionary mapping the name of each location to its description (see below). If this product is not initially available, this key may be omitted. Must be a time series. Each product may have some amount available at the beginning of each time period. In this case, the key initial amounts maps to a dictionary with the following keys: Key Description latitude (deg) The latitude of the location. longitude (deg) The longitude of the location. amount (tonne) The amount of the product initially available at the location. Must be a time series. Example { \"products\": { \"P1\": { \"initial amounts\": { \"C1\": { \"latitude (deg)\": 7.0, \"longitude (deg)\": 7.0, \"amount (tonne)\": [934.56, 934.56] }, \"C2\": { \"latitude (deg)\": 7.0, \"longitude (deg)\": 19.0, \"amount (tonne)\": [198.95, 198.95] }, \"C3\": { \"latitude (deg)\": 84.0, \"longitude (deg)\": 76.0, \"amount (tonne)\": [212.97, 212.97] } }, \"transportation cost ($/km/tonne)\": [0.015, 0.015], \"transportation energy (J/km/tonne)\": [0.12, 0.11], \"transportation emissions (tonne/km/tonne)\": { \"CO2\": [0.052, 0.050], \"CH4\": [0.003, 0.002] } }, \"P2\": { \"transportation cost ($/km/tonne)\": [0.022, 0.020] }, \"P3\": { \"transportation cost ($/km/tonne)\": [0.0125, 0.0125] }, \"P4\": { \"transportation cost ($/km/tonne)\": [0.0175, 0.0175] } } } Processing plants The plants section describes the available types of reverse manufacturing plants, their potential locations and associated costs, as well as their inputs and outputs. The field instance[\"Plants\"] is a dictionary mapping the name of the plant to a dictionary with the following keys: Key Description input The name of the product that this plant takes as input. Only one input is accepted per plant. outputs (tonne/tonne) A dictionary specifying how many tonnes of each product is produced for each tonnes of input. For example, if the plant outputs 0.5 tonnes of P2 and 0.25 tonnes of P3 for each tonnes of P1 provided, then this entry should be {\"P2\": 0.5, \"P3\": 0.25} . If the plant does not output anything, this key may be omitted. energy (GJ/tonne) The energy required to process 1 tonne of the input. Must be a time series. Optional. emissions (tonne/tonne) A dictionary mapping the name of each greenhouse gas, produced to process each tonne of input, to the amount of gas produced (in tonne). Must be a time series. Optional. locations A dictionary mapping the name of the location to a dictionary which describes the site characteristics (see below). Each type of plant is associated with a set of potential locations where it can be built. Each location is represented by a dictionary with the following keys: Key Description latitude (deg) The latitude of the location, in degrees. longitude (deg) The longitude of the location, in degrees. disposal A dictionary describing what products can be disposed locally at the plant. capacities (tonne) A dictionary describing what plant sizes are allowed, and their characteristics. The keys in the disposal dictionary should be the names of the products. The values are dictionaries with the following keys: Key Description cost ($/tonne) The cost to dispose of the product. Must be a time series. limit (tonne) The maximum amount that can be disposed of. If an unlimited amount can be disposed, this key may be omitted. Must be a time series. The keys in the capacities (tonne) dictionary should be the amounts (in tonnes). The values are dictionaries with the following keys: Key Description opening cost ($) The cost to open a plant of this size. fixed operating cost ($) The cost to keep the plant open, even if the plant doesn't process anything. Must be a time series. variable operating cost ($/tonne) The cost that the plant incurs to process each tonne of input. Must be a time series. Example { \"plants\": { \"F1\": { \"input\": \"P1\", \"outputs (tonne/tonne)\": { \"P2\": 0.2, \"P3\": 0.5 }, \"energy (GJ/tonne)\": [0.12, 0.11], \"emissions (tonne/tonne)\": { \"CO2\": [0.052, 0.050], \"CH4\": [0.003, 0.002] }, \"locations\": { \"L1\": { \"latitude (deg)\": 0.0, \"longitude (deg)\": 0.0, \"disposal\": { \"P2\": { \"cost ($/tonne)\": [-10.0, -12.0], \"limit (tonne)\": [1.0, 1.0] } }, \"capacities (tonne)\": { \"100\": { \"opening cost ($)\": [500, 530], \"fixed operating cost ($)\": [300.0, 310.0], \"variable operating cost ($/tonne)\": [5.0, 5.2] }, \"500\": { \"opening cost ($)\": [750, 760], \"fixed operating cost ($)\": [400.0, 450.0], \"variable operating cost ($/tonne)\": [5.0, 5.2] } } } } } } } Current limitations Each plant can only be opened exactly once. After open, the plant remains open until the end of the simulation. Plants can be expanded at any time, even long after they are open. All material available at the beginning of a time period must be entirely processed by the end of that time period. It is not possible to store unprocessed materials from one time period to the next. Up to two plant sizes are currently supported. Variable operating costs must be the same for all plant sizes. Output Data Format (JSON) To be documented.","title":"Data Format"},{"location":"format/#input-and-output-data-formats","text":"In this page, we describe the input and output JSON formats used by RELOG. In addition to these, RELOG can also produce simplified reports in tabular data format.","title":"Input and Output Data Formats"},{"location":"format/#input-data-format-json","text":"RELOG accepts as input a JSON file with three sections: parameters , products and plants . Below, we describe each section in more detail.","title":"Input Data Format (JSON)"},{"location":"format/#parameters","text":"The parameters section describes details about the simulation itself. Key Description time horizon (years) Number of years in the simulation. building period (years) List of years in which we are allowed to open new plants. For example, if this parameter is set to [1,2,3] , we can only open plants during the first three years. By default, this equals [1] ; that is, plants can only be opened during the first year.","title":"Parameters"},{"location":"format/#example","text":"{ \"parameters\": { \"time horizon (years)\": 2, \"building period (years)\": [1] } }","title":"Example"},{"location":"format/#products","text":"The products section describes all products and subproducts in the simulation. The field instance[\"Products\"] is a dictionary mapping the name of the product to a dictionary which describes its characteristics. Each product description contains the following keys: Key Description transportation cost ($/km/tonne) The cost to transport this product. Must be a time series. transportation energy (J/km/tonne) The energy required to transport this product. Must be a time series. Optional. transportation emissions (tonne/km/tonne) A dictionary mapping the name of each greenhouse gas, produced to transport one tonne of this product along one kilometer, to the amount of gas produced (in tonnes). Must be a time series. Optional. initial amounts A dictionary mapping the name of each location to its description (see below). If this product is not initially available, this key may be omitted. Must be a time series. Each product may have some amount available at the beginning of each time period. In this case, the key initial amounts maps to a dictionary with the following keys: Key Description latitude (deg) The latitude of the location. longitude (deg) The longitude of the location. amount (tonne) The amount of the product initially available at the location. Must be a time series.","title":"Products"},{"location":"format/#example_1","text":"{ \"products\": { \"P1\": { \"initial amounts\": { \"C1\": { \"latitude (deg)\": 7.0, \"longitude (deg)\": 7.0, \"amount (tonne)\": [934.56, 934.56] }, \"C2\": { \"latitude (deg)\": 7.0, \"longitude (deg)\": 19.0, \"amount (tonne)\": [198.95, 198.95] }, \"C3\": { \"latitude (deg)\": 84.0, \"longitude (deg)\": 76.0, \"amount (tonne)\": [212.97, 212.97] } }, \"transportation cost ($/km/tonne)\": [0.015, 0.015], \"transportation energy (J/km/tonne)\": [0.12, 0.11], \"transportation emissions (tonne/km/tonne)\": { \"CO2\": [0.052, 0.050], \"CH4\": [0.003, 0.002] } }, \"P2\": { \"transportation cost ($/km/tonne)\": [0.022, 0.020] }, \"P3\": { \"transportation cost ($/km/tonne)\": [0.0125, 0.0125] }, \"P4\": { \"transportation cost ($/km/tonne)\": [0.0175, 0.0175] } } }","title":"Example"},{"location":"format/#processing-plants","text":"The plants section describes the available types of reverse manufacturing plants, their potential locations and associated costs, as well as their inputs and outputs. The field instance[\"Plants\"] is a dictionary mapping the name of the plant to a dictionary with the following keys: Key Description input The name of the product that this plant takes as input. Only one input is accepted per plant. outputs (tonne/tonne) A dictionary specifying how many tonnes of each product is produced for each tonnes of input. For example, if the plant outputs 0.5 tonnes of P2 and 0.25 tonnes of P3 for each tonnes of P1 provided, then this entry should be {\"P2\": 0.5, \"P3\": 0.25} . If the plant does not output anything, this key may be omitted. energy (GJ/tonne) The energy required to process 1 tonne of the input. Must be a time series. Optional. emissions (tonne/tonne) A dictionary mapping the name of each greenhouse gas, produced to process each tonne of input, to the amount of gas produced (in tonne). Must be a time series. Optional. locations A dictionary mapping the name of the location to a dictionary which describes the site characteristics (see below). Each type of plant is associated with a set of potential locations where it can be built. Each location is represented by a dictionary with the following keys: Key Description latitude (deg) The latitude of the location, in degrees. longitude (deg) The longitude of the location, in degrees. disposal A dictionary describing what products can be disposed locally at the plant. capacities (tonne) A dictionary describing what plant sizes are allowed, and their characteristics. The keys in the disposal dictionary should be the names of the products. The values are dictionaries with the following keys: Key Description cost ($/tonne) The cost to dispose of the product. Must be a time series. limit (tonne) The maximum amount that can be disposed of. If an unlimited amount can be disposed, this key may be omitted. Must be a time series. The keys in the capacities (tonne) dictionary should be the amounts (in tonnes). The values are dictionaries with the following keys: Key Description opening cost ($) The cost to open a plant of this size. fixed operating cost ($) The cost to keep the plant open, even if the plant doesn't process anything. Must be a time series. variable operating cost ($/tonne) The cost that the plant incurs to process each tonne of input. Must be a time series.","title":"Processing plants"},{"location":"format/#example_2","text":"{ \"plants\": { \"F1\": { \"input\": \"P1\", \"outputs (tonne/tonne)\": { \"P2\": 0.2, \"P3\": 0.5 }, \"energy (GJ/tonne)\": [0.12, 0.11], \"emissions (tonne/tonne)\": { \"CO2\": [0.052, 0.050], \"CH4\": [0.003, 0.002] }, \"locations\": { \"L1\": { \"latitude (deg)\": 0.0, \"longitude (deg)\": 0.0, \"disposal\": { \"P2\": { \"cost ($/tonne)\": [-10.0, -12.0], \"limit (tonne)\": [1.0, 1.0] } }, \"capacities (tonne)\": { \"100\": { \"opening cost ($)\": [500, 530], \"fixed operating cost ($)\": [300.0, 310.0], \"variable operating cost ($/tonne)\": [5.0, 5.2] }, \"500\": { \"opening cost ($)\": [750, 760], \"fixed operating cost ($)\": [400.0, 450.0], \"variable operating cost ($/tonne)\": [5.0, 5.2] } } } } } } }","title":"Example"},{"location":"format/#current-limitations","text":"Each plant can only be opened exactly once. After open, the plant remains open until the end of the simulation. Plants can be expanded at any time, even long after they are open. All material available at the beginning of a time period must be entirely processed by the end of that time period. It is not possible to store unprocessed materials from one time period to the next. Up to two plant sizes are currently supported. Variable operating costs must be the same for all plant sizes.","title":"Current limitations"},{"location":"format/#output-data-format-json","text":"To be documented.","title":"Output Data Format (JSON)"},{"location":"model/","text":"Optimization Model In this page, we describe the precise mathematical optimization model used by RELOG to find the optimal logistics plan. This model is a variation of the classical Facility Location Problem, which has been widely studied in the operations research literature. To simplify the exposition, we present the simplified case where there is only one type of plant. Mathematical Description Sets $L$ - Set of locations holding the original material to be recycled $M$ - Set of materials recovered during the reverse manufacturing process $P$ - Set of potential plants to open $T = { 1, \\ldots, t^{max} } $ - Set of time periods Constants Plants: $c^\\text{disp}_{pmt}$ - Cost of disposing one tonne of material $m$ at plant $p$ during time $t$ ( $/tonne/km ) $c^\\text{exp}_{pt}$ - Cost of adding one tonne of capacity to plant $p$ at time $t$ ( $/tonne ) $c^\\text{open}_{pt}$ - Cost of opening plant $p$ at time $t$, at minimum capacity ( $ ) $c^\\text{f-base}_{pt}$ - Fixed cost of keeping plant $p$ open during time period $t$ ( $ ) $c^\\text{f-exp}_{pt}$ - Increase in fixed cost for each additional tonne of capacity ( $/tonne ) $c^\\text{var}_{pt}$ - Variable cost of processing one tonne of input at plant $p$ at time $t$ ( $/tonne ) $m^\\text{min}_p$ - Minimum capacity of plant $p$ ( tonne ) $m^\\text{max}_p$ - Maximum capacity of plant $p$ ( tonne ) $m^\\text{disp}_{pmt}$ - Maximum amount of material $m$ that plant $p$ can dispose of during time $t$ ( tonne ) Products: $\\alpha_{pm}$ - Amount of material $m$ recovered by plant $t$ for each tonne of original material ( tonne/tonne ) $m^\\text{initial}_{lt}$ - Amount of original material to be recycled at location $l$ during time $t$ ( tonne ) Transportation: $c^\\text{tr}_{t}$ - Transportation cost during time $t$ ( $/tonne/km ) $d_{lp}$ - Distance between plant $p$ and location $l$ ( km ) Decision variables $q_{mpt}$ - Amount of material $m$ recovered by plant $p$ during time $t$ ( tonne ) $u_{pt}$ - Binary variable that equals 1 if plant $p$ starts operating at time $t$ ( bool ) $w_{pt}$ - Extra capacity (amount above the minimum) added to plant $p$ during time $t$ ( tonne ) $x_{pt}$ - Binary variable that equals 1 if plant $p$ is operational at time $t$ ( bool ) $y_{lpt}$ - Amount of product sent from location $l$ to plant $p$ during time $t$ ( tonne ) $z_{mpt}$ - Amount of material $m$ disposed of by plant $p$ during time $t$ ( tonne ) Objective function RELOG minimizes the overall capital, production and transportation costs: \\begin{align*} \\text{minimize} \\;\\; & \\sum_{t \\in T} \\sum_{p \\in P} \\left[ c^\\text{open}_{pt} u_{pt} + c^\\text{f-base}_{pt} x_{pt} + \\sum_{i=1}^t c^\\text{f-exp}_{pt} w_{pi} + c^{\\text{exp}}_{pt} w_{pt} \\right] + \\\\ & \\sum_{t \\in T} \\sum_{l \\in L} \\sum_{p \\in P} \\left[ c^{\\text{tr}}_t d_{lp} + c^{\\text{var}}_{pt} \\right] y_{lpt} + \\\\ & \\sum_{t \\in T} \\sum_{p \\in P} \\sum_{m \\in M} c^{\\text{disp}}_{pmt} z_{pmt} \\end{align*} In the first line, we have (i) opening costs, if plant starts operating at time $t$, (ii) fixed operating costs, if plant is operational, (iii) additional fixed operating costs coming from expansion performed in all previous time periods up to the current one, and finally (iv) the expansion costs during the current time period. In the second line, we have the transportation costs and the variable operating costs. In the third line, we have the disposal costs. Constraints All original materials must be sent to a plant: \\begin{align} & \\sum_{p \\in P} y_{lpt} = m^\\text{initial}_{lt} & \\forall l \\in L, t \\in T \\end{align} Plants have a limited capacity: \\begin{align} & \\sum_{l \\in L} y_{lpt} \\leq m^\\text{min}_p x_p + \\sum_{i=1}^t w_p & \\forall p \\in P, t \\in T \\end{align} Plants can only be expanded up to their maximum capacity. Furthermore, if a plant is closed, it cannot be expanded: \\begin{align} & \\sum_{i=1}^t w_p \\leq m^\\text{max}_p x_p & \\forall p \\in P, t \\in T \\end{align} Amount of recovered material is proportional to the plant input: \\begin{align} & q_{mpt} = \\alpha_{pm} \\sum_{l \\in L} y_{lpt} & \\forall m \\in M, p \\in P, t \\in T \\end{align} Because we only consider a single type of plant, all recovered material must be immediately disposed of. In RELOG's full model, recovered materials may be sent to another plant for further processing. \\begin{align} & q_{mpt} = z_{mpt} & \\forall m \\in M, p \\in P, t \\in T \\end{align} A plant is operational at time $t$ if it was operational at time $t-1$ or it was built at time $t$. This constraint also prevents a plant from being built multiple times. \\begin{align} & x_{pt} = x_{p,t-1} + u_{pt} & \\forall p \\in P, t \\in T \\setminus \\{1\\} \\\\ & x_{p,1} = u_{p,1} & \\forall p \\in P \\end{align} Variable bounds: \\begin{align} & q_{mpt} \\geq 0 & \\forall m \\in M, p \\in P, t \\in T \\\\ & u_{pt} \\in \\{0,1\\} & \\forall p \\in P, t \\in T \\\\ & w_{pt} \\geq 0 & \\forall p \\in P, t \\in T \\\\ & x_{pt} \\in \\{0,1\\} & \\forall p \\in P, t \\in T \\\\ & y_{lpt} \\geq 0 & \\forall l \\in L, p \\in P, t \\in T \\\\ & m^\\text{disp}_{mpt} \\geq z_{mpt} \\geq 0 & \\forall m \\in M, p \\in P, t \\in T \\end{align} Complete optimization model \\begin{align*} \\text{minimize} \\;\\; & \\sum_{t \\in T} \\sum_{p \\in P} \\left[ c^\\text{open}_{pt} u_{pt} + c^\\text{f-base}_{pt} x_{pt} + \\sum_{i=1}^t c^\\text{f-exp}_{pt} w_{pi} + c^{\\text{exp}}_{pt} w_{pt} \\right] + \\\\ & \\sum_{t \\in T} \\sum_{l \\in L} \\sum_{p \\in P} \\left[ c^{\\text{tr}}_t d_{lp} + c^{\\text{var}}_{pt} \\right] y_{lpt} + \\\\ & \\sum_{t \\in T} \\sum_{p \\in P} \\sum_{m \\in M} c^{\\text{disp}}_{pmt} z_{pmt} \\\\ \\text{subject to } & \\sum_{p \\in P} y_{lpt} = m^\\text{initial}_{lt} & \\forall l \\in L, t \\in T \\\\ & \\sum_{l \\in L} y_{lpt} \\leq m^\\text{min}_p x_p + \\sum_{i=1}^t w_p & \\forall p \\in P, t \\in T \\\\ & \\sum_{i=1}^t w_p \\leq m^\\text{max}_p x_p & \\forall p \\in P, t \\in T \\\\ & q_{mpt} = \\alpha_{pm} \\sum_{l \\in L} y_{lpt} & \\forall m \\in M, p \\in P, t \\in T \\\\ & q_{mpt} = z_{mpt} & \\forall m \\in M, p \\in P, t \\in T \\\\ & x_{pt} = x_{p,t-1} + u_{pt} & \\forall p \\in P, t \\in T \\setminus \\{1\\} \\\\ & x_{p,1} = u_{p,1} & \\forall p \\in P \\\\ & q_{mpt} \\geq 0 & \\forall m \\in M, p \\in P, t \\in T \\\\ & u_{pt} \\in \\{0,1\\} & \\forall p \\in P, t \\in T \\\\ & w_{pt} \\geq 0 & \\forall p \\in P, t \\in T \\\\ & x_{pt} \\in \\{0,1\\} & \\forall p \\in P, t \\in T \\\\ & y_{lpt} \\geq 0 & \\forall l \\in L, p \\in P, t \\in T \\\\ & m^\\text{disp}_{mpt} \\geq z_{mpt} \\geq 0 & \\forall m \\in M, p \\in P, t \\in T \\end{align*}","title":"Optimization Model"},{"location":"model/#optimization-model","text":"In this page, we describe the precise mathematical optimization model used by RELOG to find the optimal logistics plan. This model is a variation of the classical Facility Location Problem, which has been widely studied in the operations research literature. To simplify the exposition, we present the simplified case where there is only one type of plant.","title":"Optimization Model"},{"location":"model/#mathematical-description","text":"","title":"Mathematical Description"},{"location":"model/#sets","text":"$L$ - Set of locations holding the original material to be recycled $M$ - Set of materials recovered during the reverse manufacturing process $P$ - Set of potential plants to open $T = { 1, \\ldots, t^{max} } $ - Set of time periods","title":"Sets"},{"location":"model/#constants","text":"Plants: $c^\\text{disp}_{pmt}$ - Cost of disposing one tonne of material $m$ at plant $p$ during time $t$ ( $/tonne/km ) $c^\\text{exp}_{pt}$ - Cost of adding one tonne of capacity to plant $p$ at time $t$ ( $/tonne ) $c^\\text{open}_{pt}$ - Cost of opening plant $p$ at time $t$, at minimum capacity ( $ ) $c^\\text{f-base}_{pt}$ - Fixed cost of keeping plant $p$ open during time period $t$ ( $ ) $c^\\text{f-exp}_{pt}$ - Increase in fixed cost for each additional tonne of capacity ( $/tonne ) $c^\\text{var}_{pt}$ - Variable cost of processing one tonne of input at plant $p$ at time $t$ ( $/tonne ) $m^\\text{min}_p$ - Minimum capacity of plant $p$ ( tonne ) $m^\\text{max}_p$ - Maximum capacity of plant $p$ ( tonne ) $m^\\text{disp}_{pmt}$ - Maximum amount of material $m$ that plant $p$ can dispose of during time $t$ ( tonne ) Products: $\\alpha_{pm}$ - Amount of material $m$ recovered by plant $t$ for each tonne of original material ( tonne/tonne ) $m^\\text{initial}_{lt}$ - Amount of original material to be recycled at location $l$ during time $t$ ( tonne ) Transportation: $c^\\text{tr}_{t}$ - Transportation cost during time $t$ ( $/tonne/km ) $d_{lp}$ - Distance between plant $p$ and location $l$ ( km )","title":"Constants"},{"location":"model/#decision-variables","text":"$q_{mpt}$ - Amount of material $m$ recovered by plant $p$ during time $t$ ( tonne ) $u_{pt}$ - Binary variable that equals 1 if plant $p$ starts operating at time $t$ ( bool ) $w_{pt}$ - Extra capacity (amount above the minimum) added to plant $p$ during time $t$ ( tonne ) $x_{pt}$ - Binary variable that equals 1 if plant $p$ is operational at time $t$ ( bool ) $y_{lpt}$ - Amount of product sent from location $l$ to plant $p$ during time $t$ ( tonne ) $z_{mpt}$ - Amount of material $m$ disposed of by plant $p$ during time $t$ ( tonne )","title":"Decision variables"},{"location":"model/#objective-function","text":"RELOG minimizes the overall capital, production and transportation costs: \\begin{align*} \\text{minimize} \\;\\; & \\sum_{t \\in T} \\sum_{p \\in P} \\left[ c^\\text{open}_{pt} u_{pt} + c^\\text{f-base}_{pt} x_{pt} + \\sum_{i=1}^t c^\\text{f-exp}_{pt} w_{pi} + c^{\\text{exp}}_{pt} w_{pt} \\right] + \\\\ & \\sum_{t \\in T} \\sum_{l \\in L} \\sum_{p \\in P} \\left[ c^{\\text{tr}}_t d_{lp} + c^{\\text{var}}_{pt} \\right] y_{lpt} + \\\\ & \\sum_{t \\in T} \\sum_{p \\in P} \\sum_{m \\in M} c^{\\text{disp}}_{pmt} z_{pmt} \\end{align*} In the first line, we have (i) opening costs, if plant starts operating at time $t$, (ii) fixed operating costs, if plant is operational, (iii) additional fixed operating costs coming from expansion performed in all previous time periods up to the current one, and finally (iv) the expansion costs during the current time period. In the second line, we have the transportation costs and the variable operating costs. In the third line, we have the disposal costs.","title":"Objective function"},{"location":"model/#constraints","text":"All original materials must be sent to a plant: \\begin{align} & \\sum_{p \\in P} y_{lpt} = m^\\text{initial}_{lt} & \\forall l \\in L, t \\in T \\end{align} Plants have a limited capacity: \\begin{align} & \\sum_{l \\in L} y_{lpt} \\leq m^\\text{min}_p x_p + \\sum_{i=1}^t w_p & \\forall p \\in P, t \\in T \\end{align} Plants can only be expanded up to their maximum capacity. Furthermore, if a plant is closed, it cannot be expanded: \\begin{align} & \\sum_{i=1}^t w_p \\leq m^\\text{max}_p x_p & \\forall p \\in P, t \\in T \\end{align} Amount of recovered material is proportional to the plant input: \\begin{align} & q_{mpt} = \\alpha_{pm} \\sum_{l \\in L} y_{lpt} & \\forall m \\in M, p \\in P, t \\in T \\end{align} Because we only consider a single type of plant, all recovered material must be immediately disposed of. In RELOG's full model, recovered materials may be sent to another plant for further processing. \\begin{align} & q_{mpt} = z_{mpt} & \\forall m \\in M, p \\in P, t \\in T \\end{align} A plant is operational at time $t$ if it was operational at time $t-1$ or it was built at time $t$. This constraint also prevents a plant from being built multiple times. \\begin{align} & x_{pt} = x_{p,t-1} + u_{pt} & \\forall p \\in P, t \\in T \\setminus \\{1\\} \\\\ & x_{p,1} = u_{p,1} & \\forall p \\in P \\end{align} Variable bounds: \\begin{align} & q_{mpt} \\geq 0 & \\forall m \\in M, p \\in P, t \\in T \\\\ & u_{pt} \\in \\{0,1\\} & \\forall p \\in P, t \\in T \\\\ & w_{pt} \\geq 0 & \\forall p \\in P, t \\in T \\\\ & x_{pt} \\in \\{0,1\\} & \\forall p \\in P, t \\in T \\\\ & y_{lpt} \\geq 0 & \\forall l \\in L, p \\in P, t \\in T \\\\ & m^\\text{disp}_{mpt} \\geq z_{mpt} \\geq 0 & \\forall m \\in M, p \\in P, t \\in T \\end{align}","title":"Constraints"},{"location":"model/#complete-optimization-model","text":"\\begin{align*} \\text{minimize} \\;\\; & \\sum_{t \\in T} \\sum_{p \\in P} \\left[ c^\\text{open}_{pt} u_{pt} + c^\\text{f-base}_{pt} x_{pt} + \\sum_{i=1}^t c^\\text{f-exp}_{pt} w_{pi} + c^{\\text{exp}}_{pt} w_{pt} \\right] + \\\\ & \\sum_{t \\in T} \\sum_{l \\in L} \\sum_{p \\in P} \\left[ c^{\\text{tr}}_t d_{lp} + c^{\\text{var}}_{pt} \\right] y_{lpt} + \\\\ & \\sum_{t \\in T} \\sum_{p \\in P} \\sum_{m \\in M} c^{\\text{disp}}_{pmt} z_{pmt} \\\\ \\text{subject to } & \\sum_{p \\in P} y_{lpt} = m^\\text{initial}_{lt} & \\forall l \\in L, t \\in T \\\\ & \\sum_{l \\in L} y_{lpt} \\leq m^\\text{min}_p x_p + \\sum_{i=1}^t w_p & \\forall p \\in P, t \\in T \\\\ & \\sum_{i=1}^t w_p \\leq m^\\text{max}_p x_p & \\forall p \\in P, t \\in T \\\\ & q_{mpt} = \\alpha_{pm} \\sum_{l \\in L} y_{lpt} & \\forall m \\in M, p \\in P, t \\in T \\\\ & q_{mpt} = z_{mpt} & \\forall m \\in M, p \\in P, t \\in T \\\\ & x_{pt} = x_{p,t-1} + u_{pt} & \\forall p \\in P, t \\in T \\setminus \\{1\\} \\\\ & x_{p,1} = u_{p,1} & \\forall p \\in P \\\\ & q_{mpt} \\geq 0 & \\forall m \\in M, p \\in P, t \\in T \\\\ & u_{pt} \\in \\{0,1\\} & \\forall p \\in P, t \\in T \\\\ & w_{pt} \\geq 0 & \\forall p \\in P, t \\in T \\\\ & x_{pt} \\in \\{0,1\\} & \\forall p \\in P, t \\in T \\\\ & y_{lpt} \\geq 0 & \\forall l \\in L, p \\in P, t \\in T \\\\ & m^\\text{disp}_{mpt} \\geq z_{mpt} \\geq 0 & \\forall m \\in M, p \\in P, t \\in T \\end{align*}","title":"Complete optimization model"},{"location":"reports/","text":"Simplified Solution Reports In addition to the full output format described in data formats , RELOG can also generate a number of simplified reports in tabular data format (CSV), which can be more easily processed by spreadsheet software (such as Microsoft Excel), by data analysis libraries (such as Pandas) or by relational databases (such as SQLite). In this page, we also illustrate what types of charts and visualizations can be produced from these tabular data files. The sample charts have been produced using Python, matplotlib, seaborn and geopandas. Plants report Report showing plant costs, capacities, energy expenditure and utilization factors. Generated by RELOG.write_plants_report(solution, filename) . For a concrete example, see nimh_plants.csv . Column Description plant type Plant type. location name Location name. year What year this row corresponds to. This reports includes one row for each year in the simulation. latitude (deg) Latitude of the plant. longitude (deg) Longitude of the plant. capacity (tonne) Capacity of the plant at this point in time. amount processed (tonne) Amount of input material received by the plant this year. utilization factor (%) Amount processed by the plant this year divided by current plant capacity. energy (GJ) Amount of energy expended by the plant this year. opening cost ($) Amount spent opening the plant. This value is only positive if the plant became operational this year. expansion cost ($) Amount spent this year expanding the plant capacity. fixed operating cost ($) Amount spent for keeping the plant operational this year. variable operating cost ($) Amount spent for processing the input material this year. total cost ($) Sum of all previous plant costs. Sample charts Bar plot with total plant costs per year, grouped by plant type (in Python): import pandas as pd import seaborn as sns; sns.set() data = pd.read_csv(\"plants_report.csv\") sns.barplot(x=\"year\", y=\"total cost ($)\", hue=\"plant type\", data=data.groupby([\"plant type\", \"year\"]) .sum() .reset_index()); Map showing plant locations (in Python): import pandas as pd import geopandas as gp # Plot base map world = gp.read_file(gp.datasets.get_path('naturalearth_lowres')) ax = world.plot(color='white', edgecolor='50', figsize=(13,6)) ax.set_ylim([23, 50]) ax.set_xlim([-128, -65]) # Plot plant locations data = pd.read_csv(\"nimh_plants.csv\") points = gp.points_from_xy(data[\"longitude (deg)\"], data[\"latitude (deg)\"]) gp.GeoDataFrame(data, geometry=points).plot(ax=ax); Plant outputs report Report showing amount of products produced, sent and disposed of by each plant, as well as disposal costs. Generated by RELOG.write_plant_outputs_report(solution, filename) . For a concrete example, see nimh_plant_outputs.csv . Column Description plant type Plant type. location name Location name. year What year this row corresponds to. This reports includes one row for each year in the simulation. product Product being produced. amount produced (tonne) Amount of product produced this year. amount sent (tonne) Amount of product produced by this plant and sent to another plant for further processing this year. amount disposed (tonne) Amount produced produced by this plant and immediately disposed of locally this year. disposal cost ($) Disposal cost for this year. Sample charts Bar plot showing total amount produced for each product, grouped by year (in Python): import pandas as pd import seaborn as sns; sns.set() data = pd.read_csv(\"plant_outputs_report.csv\") sns.barplot(x=\"amount produced (tonne)\", y=\"product name\", hue=\"year\", data=data.groupby([\"product name\", \"year\"]) .sum() .reset_index()); Plant emissions report Report showing amount of emissions produced by each plant. Generated by RELOG.write_plant_emissions_report(solution, filename) . For a concrete example, see nimh_plant_emissions.csv . Column Description plant type Plant type. location name Location name. year Year. emission type Type of emission. amount (tonne) Amount of emission produced by the plant this year. Sample charts Bar plot showing total emission by plant type, grouped type of emissions (in Python): import pandas as pd import seaborn as sns; sns.set() data = pd.read_csv(\"plant_emissions_report.csv\") sns.barplot(x=\"plant type\", y=\"emission amount (tonne)\", hue=\"emission type\", data=data.groupby([\"plant type\", \"emission type\"]) .sum() .reset_index()); Transportation report Report showing amount of product sent from initial locations to plants, and from one plant to another. Includes the distance between each pair of locations, amount-distance shipped, transportation costs and energy expenditure. Generated by RELOG.write_transportation_report(solution, filename) . For a concrete example, see nimh_transportation.csv . Column Description source type If product is being shipped from an initial location, equals Origin . If product is being shipped from a plant, equals plant type. source location name Name of the location where the product is being shipped from. source latitude (deg) Latitude of the source location. source longitude (deg) Longitude of the source location. destination type Type of plant the product is being shipped to. destination location name Name of the location where the product is being shipped to. destination latitude (deg) Latitude of the destination location. destination longitude (deg) Longitude of the destination location. product Product being shipped. year Year. distance (km) Distance between source and destination. amount (tonne) Total amount of product being shipped between the two locations this year. amount-distance (tonne-km) Total amount being shipped this year times distance. transportation cost ($) Cost to transport this amount of product between the two locations for this year. transportation energy (GJ) Energy expended transporting this amount of product between the two locations. Sample charts Bar plot showing total amount-distance for each product type, grouped by year (in Python): import pandas as pd import seaborn as sns; sns.set() data = pd.read_csv(\"transportation_report.csv\") sns.barplot(x=\"product\", y=\"amount-distance (tonne-km)\", hue=\"year\", data=data.groupby([\"product\", \"year\"]) .sum() .reset_index()); Map of transportation lines (in Python): import pandas as pd import geopandas as gp from shapely.geometry import Point, LineString import matplotlib.pyplot as plt from matplotlib import collections # Plot base map world = gp.read_file(gp.datasets.get_path('naturalearth_lowres')) ax = world.plot(color='white', edgecolor='50', figsize=(14,7)) ax.set_ylim([23, 50]) ax.set_xlim([-128, -65]) # Draw transportation lines data = pd.read_csv(\"transportation_report.csv\") lines = [[(row[\"source longitude (deg)\"], row[\"source latitude (deg)\"]), (row[\"destination longitude (deg)\"], row[\"destination latitude (deg)\"]) ] for (index, row) in data.iterrows()] ax.add_collection(collections.LineCollection(lines, linewidths=0.25, zorder=1, alpha=0.5, color=\"50\")) # Draw source points points = gp.points_from_xy(data[\"source longitude (deg)\"], data[\"source latitude (deg)\"]) gp.GeoDataFrame(data, geometry=points).plot(ax=ax, color=\"0.5\", markersize=1); # Draw destination points points = gp.points_from_xy(data[\"destination longitude (deg)\"], data[\"destination latitude (deg)\"]) gp.GeoDataFrame(data, geometry=points).plot(ax=ax, color=\"red\", markersize=50); Transportation emissions report Report showing emissions for each trip between initial locations and plants, and between pairs of plants. Generated by RELOG.write_transportation_emissions_report(solution, filename) . For a concrete example, see nimh_transportation_emissions.csv . Column Description source type If product is being shipped from an initial location, equals Origin . If product is being shipped from a plant, equals plant type. source location name Name of the location where the product is being shipped from. source latitude (deg) Latitude of the source location. source longitude (deg) Longitude of the source location. destination type Type of plant the product is being shipped to. destination location name Name of the location where the product is being shipped to. destination latitude (deg) Latitude of the destination location. destination longitude (deg) Longitude of the destination location. product Product being shipped. year Year. distance (km) Distance between source and destination. shipped amount (tonne) Total amount of product being shipped between the two locations this year. shipped amount-distance (tonne-km) Total amount being shipped this year times distance. emission type Type of emission. emission amount (tonne) Amount of emission produced by transportation segment this year. Sample charts Bar plot showing total emission amount by emission type, grouped by type of product being transported (in Python): import pandas as pd import seaborn as sns; sns.set() data = pd.read_csv(\"transportation_emissions_report.csv\") sns.barplot(x=\"emission type\", y=\"emission amount (tonne)\", hue=\"product\", data=data.groupby([\"product\", \"emission type\"]) .sum() .reset_index());","title":"Reports"},{"location":"reports/#simplified-solution-reports","text":"In addition to the full output format described in data formats , RELOG can also generate a number of simplified reports in tabular data format (CSV), which can be more easily processed by spreadsheet software (such as Microsoft Excel), by data analysis libraries (such as Pandas) or by relational databases (such as SQLite). In this page, we also illustrate what types of charts and visualizations can be produced from these tabular data files. The sample charts have been produced using Python, matplotlib, seaborn and geopandas.","title":"Simplified Solution Reports"},{"location":"reports/#plants-report","text":"Report showing plant costs, capacities, energy expenditure and utilization factors. Generated by RELOG.write_plants_report(solution, filename) . For a concrete example, see nimh_plants.csv . Column Description plant type Plant type. location name Location name. year What year this row corresponds to. This reports includes one row for each year in the simulation. latitude (deg) Latitude of the plant. longitude (deg) Longitude of the plant. capacity (tonne) Capacity of the plant at this point in time. amount processed (tonne) Amount of input material received by the plant this year. utilization factor (%) Amount processed by the plant this year divided by current plant capacity. energy (GJ) Amount of energy expended by the plant this year. opening cost ($) Amount spent opening the plant. This value is only positive if the plant became operational this year. expansion cost ($) Amount spent this year expanding the plant capacity. fixed operating cost ($) Amount spent for keeping the plant operational this year. variable operating cost ($) Amount spent for processing the input material this year. total cost ($) Sum of all previous plant costs.","title":"Plants report"},{"location":"reports/#sample-charts","text":"Bar plot with total plant costs per year, grouped by plant type (in Python): import pandas as pd import seaborn as sns; sns.set() data = pd.read_csv(\"plants_report.csv\") sns.barplot(x=\"year\", y=\"total cost ($)\", hue=\"plant type\", data=data.groupby([\"plant type\", \"year\"]) .sum() .reset_index()); Map showing plant locations (in Python): import pandas as pd import geopandas as gp # Plot base map world = gp.read_file(gp.datasets.get_path('naturalearth_lowres')) ax = world.plot(color='white', edgecolor='50', figsize=(13,6)) ax.set_ylim([23, 50]) ax.set_xlim([-128, -65]) # Plot plant locations data = pd.read_csv(\"nimh_plants.csv\") points = gp.points_from_xy(data[\"longitude (deg)\"], data[\"latitude (deg)\"]) gp.GeoDataFrame(data, geometry=points).plot(ax=ax);","title":"Sample charts"},{"location":"reports/#plant-outputs-report","text":"Report showing amount of products produced, sent and disposed of by each plant, as well as disposal costs. Generated by RELOG.write_plant_outputs_report(solution, filename) . For a concrete example, see nimh_plant_outputs.csv . Column Description plant type Plant type. location name Location name. year What year this row corresponds to. This reports includes one row for each year in the simulation. product Product being produced. amount produced (tonne) Amount of product produced this year. amount sent (tonne) Amount of product produced by this plant and sent to another plant for further processing this year. amount disposed (tonne) Amount produced produced by this plant and immediately disposed of locally this year. disposal cost ($) Disposal cost for this year.","title":"Plant outputs report"},{"location":"reports/#sample-charts_1","text":"Bar plot showing total amount produced for each product, grouped by year (in Python): import pandas as pd import seaborn as sns; sns.set() data = pd.read_csv(\"plant_outputs_report.csv\") sns.barplot(x=\"amount produced (tonne)\", y=\"product name\", hue=\"year\", data=data.groupby([\"product name\", \"year\"]) .sum() .reset_index());","title":"Sample charts"},{"location":"reports/#plant-emissions-report","text":"Report showing amount of emissions produced by each plant. Generated by RELOG.write_plant_emissions_report(solution, filename) . For a concrete example, see nimh_plant_emissions.csv . Column Description plant type Plant type. location name Location name. year Year. emission type Type of emission. amount (tonne) Amount of emission produced by the plant this year.","title":"Plant emissions report"},{"location":"reports/#sample-charts_2","text":"Bar plot showing total emission by plant type, grouped type of emissions (in Python): import pandas as pd import seaborn as sns; sns.set() data = pd.read_csv(\"plant_emissions_report.csv\") sns.barplot(x=\"plant type\", y=\"emission amount (tonne)\", hue=\"emission type\", data=data.groupby([\"plant type\", \"emission type\"]) .sum() .reset_index());","title":"Sample charts"},{"location":"reports/#transportation-report","text":"Report showing amount of product sent from initial locations to plants, and from one plant to another. Includes the distance between each pair of locations, amount-distance shipped, transportation costs and energy expenditure. Generated by RELOG.write_transportation_report(solution, filename) . For a concrete example, see nimh_transportation.csv . Column Description source type If product is being shipped from an initial location, equals Origin . If product is being shipped from a plant, equals plant type. source location name Name of the location where the product is being shipped from. source latitude (deg) Latitude of the source location. source longitude (deg) Longitude of the source location. destination type Type of plant the product is being shipped to. destination location name Name of the location where the product is being shipped to. destination latitude (deg) Latitude of the destination location. destination longitude (deg) Longitude of the destination location. product Product being shipped. year Year. distance (km) Distance between source and destination. amount (tonne) Total amount of product being shipped between the two locations this year. amount-distance (tonne-km) Total amount being shipped this year times distance. transportation cost ($) Cost to transport this amount of product between the two locations for this year. transportation energy (GJ) Energy expended transporting this amount of product between the two locations.","title":"Transportation report"},{"location":"reports/#sample-charts_3","text":"Bar plot showing total amount-distance for each product type, grouped by year (in Python): import pandas as pd import seaborn as sns; sns.set() data = pd.read_csv(\"transportation_report.csv\") sns.barplot(x=\"product\", y=\"amount-distance (tonne-km)\", hue=\"year\", data=data.groupby([\"product\", \"year\"]) .sum() .reset_index()); Map of transportation lines (in Python): import pandas as pd import geopandas as gp from shapely.geometry import Point, LineString import matplotlib.pyplot as plt from matplotlib import collections # Plot base map world = gp.read_file(gp.datasets.get_path('naturalearth_lowres')) ax = world.plot(color='white', edgecolor='50', figsize=(14,7)) ax.set_ylim([23, 50]) ax.set_xlim([-128, -65]) # Draw transportation lines data = pd.read_csv(\"transportation_report.csv\") lines = [[(row[\"source longitude (deg)\"], row[\"source latitude (deg)\"]), (row[\"destination longitude (deg)\"], row[\"destination latitude (deg)\"]) ] for (index, row) in data.iterrows()] ax.add_collection(collections.LineCollection(lines, linewidths=0.25, zorder=1, alpha=0.5, color=\"50\")) # Draw source points points = gp.points_from_xy(data[\"source longitude (deg)\"], data[\"source latitude (deg)\"]) gp.GeoDataFrame(data, geometry=points).plot(ax=ax, color=\"0.5\", markersize=1); # Draw destination points points = gp.points_from_xy(data[\"destination longitude (deg)\"], data[\"destination latitude (deg)\"]) gp.GeoDataFrame(data, geometry=points).plot(ax=ax, color=\"red\", markersize=50);","title":"Sample charts"},{"location":"reports/#transportation-emissions-report","text":"Report showing emissions for each trip between initial locations and plants, and between pairs of plants. Generated by RELOG.write_transportation_emissions_report(solution, filename) . For a concrete example, see nimh_transportation_emissions.csv . Column Description source type If product is being shipped from an initial location, equals Origin . If product is being shipped from a plant, equals plant type. source location name Name of the location where the product is being shipped from. source latitude (deg) Latitude of the source location. source longitude (deg) Longitude of the source location. destination type Type of plant the product is being shipped to. destination location name Name of the location where the product is being shipped to. destination latitude (deg) Latitude of the destination location. destination longitude (deg) Longitude of the destination location. product Product being shipped. year Year. distance (km) Distance between source and destination. shipped amount (tonne) Total amount of product being shipped between the two locations this year. shipped amount-distance (tonne-km) Total amount being shipped this year times distance. emission type Type of emission. emission amount (tonne) Amount of emission produced by transportation segment this year.","title":"Transportation emissions report"},{"location":"reports/#sample-charts_4","text":"Bar plot showing total emission amount by emission type, grouped by type of product being transported (in Python): import pandas as pd import seaborn as sns; sns.set() data = pd.read_csv(\"transportation_emissions_report.csv\") sns.barplot(x=\"emission type\", y=\"emission amount (tonne)\", hue=\"product\", data=data.groupby([\"product\", \"emission type\"]) .sum() .reset_index());","title":"Sample charts"},{"location":"usage/","text":"Usage 1. Installation To use RELOG, the first step is to install the Julia programming language on your machine. Note that RELOG was developed and tested with Julia 1.5 and may not be compatible with newer versions. After Julia is installed, launch the Julia console, type ] to switch to package manger mode, then run: (@v1.5) pkg> add https://github.com/ANL-CEEESA/RELOG.git After the package and all its dependencies have been installed, please run the RELOG test suite, as shown below, to make sure that the package has been correctly installed: (@v1.5) pkg> test RELOG To update the package to a newer version, type ] to enter the package manager mode, then run: (@v1.5) pkg> update RELOG 2. Modeling the problem The two main model components in RELOG are products and plants . A product is any material that needs to be recycled, any intermediary product produced during the recycling process, or any product recovered at the end of the process. For example, in a NiMH battery recycling study case, products could include (i) the original batteries to be recycled; (ii) the cathode and anode parts of the battery; (iii) rare-earth elements and (iv) scrap metals. The model assumes that some products are initially available at user-specified locations (described by their latitude, longitude and the amount available), while other products only become available during the recycling process. Transporting products from one location to another incurs a transportation cost ( $/km/tonne ), spends some amount of energy ( J/km/tonne ) and may generate multiple types of emissions ( tonne/tonne ). All these parameters are user-specified and may be product- and time-specific. A plant is a facility that converts one type of product to another. RELOG assumes that each plant receives a single type of product as input and converts this input into multiple types of products. Multiple types of plants, with different inputs, outputs and performance characteristics, may be specified. In the NiMH battery recycling study case, for example, one type of plant could be a disassembly plant , which converts batteries into cathode and anode . Another type of plant could be anode recycling plant , which converts anode into rare-earth elements and scrap metals . To process each tonne of input material, plants incur a variable operating cost ( $/tonne ), spend some amount of energy ( GJ/tonne ), and produce multiple types of emissions ( tonne/tonne ). Plants also incur a fixed operating cost ( $ ) regardless of the amount of material they process. All these parameters are user-specified and may be region- and time-specific. Plants can be built at user-specified potential locations. Opening a plant incurs a one-time opening cost ( $ ) which may be region- and time-specific. Plants also have a limited capacity (in tonne ), which indicates the maximum amount of input material they are able to process per year. When specifying potential locations for each type of plant, it is also possible to specify the minimum and maximum capacity of the plants that can be built at that particular location. Different plants sizes may have different opening costs and fixed operating costs. After a plant is built, it can be further expanded in the following years, up to its maximum capacity. All products that are initially available must be sent to a plant for processing. All products that are generated by a plant can either be sent to another plant for further processing, or disposed of locally for either a profit or a loss ( $/tonne ). To model environmental regulations, it is also possible to specify the maximum amount of each product that can be disposed of at each location. All user parameters specified above must be provided to RELOG as a JSON file, which is fully described in the data format page . 3. Running the optimization After creating a JSON file describing the reverse manufacturing process and the input data, the following example illustrates how to use the package to find the optimal set of decisions: # Import package using RELOG # Solve optimization problem solution = RELOG.solve(\"/home/user/instance.json\") # Write full solution in JSON format RELOG.write(solution, \"solution.json\") # Write simplified reports in CSV format RELOG.write_plants_report(solution, \"plants.csv\") RELOG.write_transportation_report(solution, \"transportation.csv\") For a complete description of the file formats above, and for a complete list of available reports, see the data format page . 4. Advanced options 4.1 Changing the solver By default, RELOG internally uses Cbc , an open-source and freely-available Mixed-Integer Linear Programming solver developed by the COIN-OR Project . For larger-scale test cases, a commercial solver such as Gurobi, CPLEX or XPRESS is recommended. The following snippet shows how to switch from Cbc to Gurobi, for example: using RELOG, Gurobi, JuMP gurobi = optimizer_with_attributes(Gurobi.Optimizer, \"TimeLimit\" => 3600, \"MIPGap\" => 0.001) RELOG.solve(\"instance.json\", output=\"solution.json\", optimizer=gurobi)","title":"Usage"},{"location":"usage/#usage","text":"","title":"Usage"},{"location":"usage/#1-installation","text":"To use RELOG, the first step is to install the Julia programming language on your machine. Note that RELOG was developed and tested with Julia 1.5 and may not be compatible with newer versions. After Julia is installed, launch the Julia console, type ] to switch to package manger mode, then run: (@v1.5) pkg> add https://github.com/ANL-CEEESA/RELOG.git After the package and all its dependencies have been installed, please run the RELOG test suite, as shown below, to make sure that the package has been correctly installed: (@v1.5) pkg> test RELOG To update the package to a newer version, type ] to enter the package manager mode, then run: (@v1.5) pkg> update RELOG","title":"1. Installation"},{"location":"usage/#2-modeling-the-problem","text":"The two main model components in RELOG are products and plants . A product is any material that needs to be recycled, any intermediary product produced during the recycling process, or any product recovered at the end of the process. For example, in a NiMH battery recycling study case, products could include (i) the original batteries to be recycled; (ii) the cathode and anode parts of the battery; (iii) rare-earth elements and (iv) scrap metals. The model assumes that some products are initially available at user-specified locations (described by their latitude, longitude and the amount available), while other products only become available during the recycling process. Transporting products from one location to another incurs a transportation cost ( $/km/tonne ), spends some amount of energy ( J/km/tonne ) and may generate multiple types of emissions ( tonne/tonne ). All these parameters are user-specified and may be product- and time-specific. A plant is a facility that converts one type of product to another. RELOG assumes that each plant receives a single type of product as input and converts this input into multiple types of products. Multiple types of plants, with different inputs, outputs and performance characteristics, may be specified. In the NiMH battery recycling study case, for example, one type of plant could be a disassembly plant , which converts batteries into cathode and anode . Another type of plant could be anode recycling plant , which converts anode into rare-earth elements and scrap metals . To process each tonne of input material, plants incur a variable operating cost ( $/tonne ), spend some amount of energy ( GJ/tonne ), and produce multiple types of emissions ( tonne/tonne ). Plants also incur a fixed operating cost ( $ ) regardless of the amount of material they process. All these parameters are user-specified and may be region- and time-specific. Plants can be built at user-specified potential locations. Opening a plant incurs a one-time opening cost ( $ ) which may be region- and time-specific. Plants also have a limited capacity (in tonne ), which indicates the maximum amount of input material they are able to process per year. When specifying potential locations for each type of plant, it is also possible to specify the minimum and maximum capacity of the plants that can be built at that particular location. Different plants sizes may have different opening costs and fixed operating costs. After a plant is built, it can be further expanded in the following years, up to its maximum capacity. All products that are initially available must be sent to a plant for processing. All products that are generated by a plant can either be sent to another plant for further processing, or disposed of locally for either a profit or a loss ( $/tonne ). To model environmental regulations, it is also possible to specify the maximum amount of each product that can be disposed of at each location. All user parameters specified above must be provided to RELOG as a JSON file, which is fully described in the data format page .","title":"2. Modeling the problem"},{"location":"usage/#3-running-the-optimization","text":"After creating a JSON file describing the reverse manufacturing process and the input data, the following example illustrates how to use the package to find the optimal set of decisions: # Import package using RELOG # Solve optimization problem solution = RELOG.solve(\"/home/user/instance.json\") # Write full solution in JSON format RELOG.write(solution, \"solution.json\") # Write simplified reports in CSV format RELOG.write_plants_report(solution, \"plants.csv\") RELOG.write_transportation_report(solution, \"transportation.csv\") For a complete description of the file formats above, and for a complete list of available reports, see the data format page .","title":"3. Running the optimization"},{"location":"usage/#4-advanced-options","text":"","title":"4. Advanced options"},{"location":"usage/#41-changing-the-solver","text":"By default, RELOG internally uses Cbc , an open-source and freely-available Mixed-Integer Linear Programming solver developed by the COIN-OR Project . For larger-scale test cases, a commercial solver such as Gurobi, CPLEX or XPRESS is recommended. The following snippet shows how to switch from Cbc to Gurobi, for example: using RELOG, Gurobi, JuMP gurobi = optimizer_with_attributes(Gurobi.Optimizer, \"TimeLimit\" => 3600, \"MIPGap\" => 0.001) RELOG.solve(\"instance.json\", output=\"solution.json\", optimizer=gurobi)","title":"4.1 Changing the solver"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"RELOG: Reverse Logistics Optimization RELOG is an open-source supply chain optimization package focusing on reverse logistics and reverse manufacturing. The package uses Mixed-Integer Linear Programming to determine where to build recycling plants, what size should these plants have and which customers should be served by which plants. The package supports custom reverse logistics pipelines, with multiple types of plants, multiple types of product and multiple time periods. Table of Contents Usage Input and Output Data Formats Simplified Solution Reports Optimization Model Source Code https://github.com/ANL-CEEESA/RELOG Authors Alinson S. Xavier, Argonne National Laboratory < axavier@anl.gov > Nwike Iloeje, Argonne National Laboratory < ciloeje@anl.gov > License RELOG: Reverse Logistics Optimization Copyright \u00a9 2020, UChicago Argonne, LLC. All Rights Reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.","title":"Home"},{"location":"#relog-reverse-logistics-optimization","text":"RELOG is an open-source supply chain optimization package focusing on reverse logistics and reverse manufacturing. The package uses Mixed-Integer Linear Programming to determine where to build recycling plants, what size should these plants have and which customers should be served by which plants. The package supports custom reverse logistics pipelines, with multiple types of plants, multiple types of product and multiple time periods.","title":"RELOG: Reverse Logistics Optimization"},{"location":"#table-of-contents","text":"Usage Input and Output Data Formats Simplified Solution Reports Optimization Model","title":"Table of Contents"},{"location":"#source-code","text":"https://github.com/ANL-CEEESA/RELOG","title":"Source Code"},{"location":"#authors","text":"Alinson S. Xavier, Argonne National Laboratory < axavier@anl.gov > Nwike Iloeje, Argonne National Laboratory < ciloeje@anl.gov >","title":"Authors"},{"location":"#license","text":"RELOG: Reverse Logistics Optimization Copyright \u00a9 2020, UChicago Argonne, LLC. All Rights Reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.","title":"License"},{"location":"format/","text":"Input and Output Data Formats In this page, we describe the input and output JSON formats used by RELOG. In addition to these, RELOG can also produce simplified reports in tabular data format. Input Data Format (JSON) RELOG accepts as input a JSON file with three sections: parameters , products and plants . Below, we describe each section in more detail. Parameters The parameters section describes details about the simulation itself. Key Description time horizon (years) Number of years in the simulation. building period (years) List of years in which we are allowed to open new plants. For example, if this parameter is set to [1,2,3] , we can only open plants during the first three years. By default, this equals [1] ; that is, plants can only be opened during the first year. Example { \"parameters\": { \"time horizon (years)\": 2, \"building period (years)\": [1] } } Products The products section describes all products and subproducts in the simulation. The field instance[\"Products\"] is a dictionary mapping the name of the product to a dictionary which describes its characteristics. Each product description contains the following keys: Key Description transportation cost ($/km/tonne) The cost to transport this product. Must be a time series. transportation energy (J/km/tonne) The energy required to transport this product. Must be a time series. Optional. transportation emissions (tonne/km/tonne) A dictionary mapping the name of each greenhouse gas, produced to transport one tonne of this product along one kilometer, to the amount of gas produced (in tonnes). Must be a time series. Optional. initial amounts A dictionary mapping the name of each location to its description (see below). If this product is not initially available, this key may be omitted. Must be a time series. Each product may have some amount available at the beginning of each time period. In this case, the key initial amounts maps to a dictionary with the following keys: Key Description latitude (deg) The latitude of the location. longitude (deg) The longitude of the location. amount (tonne) The amount of the product initially available at the location. Must be a time series. Example { \"products\": { \"P1\": { \"initial amounts\": { \"C1\": { \"latitude (deg)\": 7.0, \"longitude (deg)\": 7.0, \"amount (tonne)\": [934.56, 934.56] }, \"C2\": { \"latitude (deg)\": 7.0, \"longitude (deg)\": 19.0, \"amount (tonne)\": [198.95, 198.95] }, \"C3\": { \"latitude (deg)\": 84.0, \"longitude (deg)\": 76.0, \"amount (tonne)\": [212.97, 212.97] } }, \"transportation cost ($/km/tonne)\": [0.015, 0.015], \"transportation energy (J/km/tonne)\": [0.12, 0.11], \"transportation emissions (tonne/km/tonne)\": { \"CO2\": [0.052, 0.050], \"CH4\": [0.003, 0.002] } }, \"P2\": { \"transportation cost ($/km/tonne)\": [0.022, 0.020] }, \"P3\": { \"transportation cost ($/km/tonne)\": [0.0125, 0.0125] }, \"P4\": { \"transportation cost ($/km/tonne)\": [0.0175, 0.0175] } } } Processing plants The plants section describes the available types of reverse manufacturing plants, their potential locations and associated costs, as well as their inputs and outputs. The field instance[\"Plants\"] is a dictionary mapping the name of the plant to a dictionary with the following keys: Key Description input The name of the product that this plant takes as input. Only one input is accepted per plant. outputs (tonne/tonne) A dictionary specifying how many tonnes of each product is produced for each tonnes of input. For example, if the plant outputs 0.5 tonnes of P2 and 0.25 tonnes of P3 for each tonnes of P1 provided, then this entry should be {\"P2\": 0.5, \"P3\": 0.25} . If the plant does not output anything, this key may be omitted. energy (GJ/tonne) The energy required to process 1 tonne of the input. Must be a time series. Optional. emissions (tonne/tonne) A dictionary mapping the name of each greenhouse gas, produced to process each tonne of input, to the amount of gas produced (in tonne). Must be a time series. Optional. locations A dictionary mapping the name of the location to a dictionary which describes the site characteristics (see below). Each type of plant is associated with a set of potential locations where it can be built. Each location is represented by a dictionary with the following keys: Key Description latitude (deg) The latitude of the location, in degrees. longitude (deg) The longitude of the location, in degrees. disposal A dictionary describing what products can be disposed locally at the plant. capacities (tonne) A dictionary describing what plant sizes are allowed, and their characteristics. The keys in the disposal dictionary should be the names of the products. The values are dictionaries with the following keys: Key Description cost ($/tonne) The cost to dispose of the product. Must be a time series. limit (tonne) The maximum amount that can be disposed of. If an unlimited amount can be disposed, this key may be omitted. Must be a time series. The keys in the capacities (tonne) dictionary should be the amounts (in tonnes). The values are dictionaries with the following keys: Key Description opening cost ($) The cost to open a plant of this size. fixed operating cost ($) The cost to keep the plant open, even if the plant doesn't process anything. Must be a time series. variable operating cost ($/tonne) The cost that the plant incurs to process each tonne of input. Must be a time series. Example { \"plants\": { \"F1\": { \"input\": \"P1\", \"outputs (tonne/tonne)\": { \"P2\": 0.2, \"P3\": 0.5 }, \"energy (GJ/tonne)\": [0.12, 0.11], \"emissions (tonne/tonne)\": { \"CO2\": [0.052, 0.050], \"CH4\": [0.003, 0.002] }, \"locations\": { \"L1\": { \"latitude (deg)\": 0.0, \"longitude (deg)\": 0.0, \"disposal\": { \"P2\": { \"cost ($/tonne)\": [-10.0, -12.0], \"limit (tonne)\": [1.0, 1.0] } }, \"capacities (tonne)\": { \"100\": { \"opening cost ($)\": [500, 530], \"fixed operating cost ($)\": [300.0, 310.0], \"variable operating cost ($/tonne)\": [5.0, 5.2] }, \"500\": { \"opening cost ($)\": [750, 760], \"fixed operating cost ($)\": [400.0, 450.0], \"variable operating cost ($/tonne)\": [5.0, 5.2] } } } } } } } Current limitations Each plant can only be opened exactly once. After open, the plant remains open until the end of the simulation. Plants can be expanded at any time, even long after they are open. All material available at the beginning of a time period must be entirely processed by the end of that time period. It is not possible to store unprocessed materials from one time period to the next. Up to two plant sizes are currently supported. Variable operating costs must be the same for all plant sizes. Output Data Format (JSON) To be documented.","title":"Data Format"},{"location":"format/#input-and-output-data-formats","text":"In this page, we describe the input and output JSON formats used by RELOG. In addition to these, RELOG can also produce simplified reports in tabular data format.","title":"Input and Output Data Formats"},{"location":"format/#input-data-format-json","text":"RELOG accepts as input a JSON file with three sections: parameters , products and plants . Below, we describe each section in more detail.","title":"Input Data Format (JSON)"},{"location":"format/#parameters","text":"The parameters section describes details about the simulation itself. Key Description time horizon (years) Number of years in the simulation. building period (years) List of years in which we are allowed to open new plants. For example, if this parameter is set to [1,2,3] , we can only open plants during the first three years. By default, this equals [1] ; that is, plants can only be opened during the first year.","title":"Parameters"},{"location":"format/#example","text":"{ \"parameters\": { \"time horizon (years)\": 2, \"building period (years)\": [1] } }","title":"Example"},{"location":"format/#products","text":"The products section describes all products and subproducts in the simulation. The field instance[\"Products\"] is a dictionary mapping the name of the product to a dictionary which describes its characteristics. Each product description contains the following keys: Key Description transportation cost ($/km/tonne) The cost to transport this product. Must be a time series. transportation energy (J/km/tonne) The energy required to transport this product. Must be a time series. Optional. transportation emissions (tonne/km/tonne) A dictionary mapping the name of each greenhouse gas, produced to transport one tonne of this product along one kilometer, to the amount of gas produced (in tonnes). Must be a time series. Optional. initial amounts A dictionary mapping the name of each location to its description (see below). If this product is not initially available, this key may be omitted. Must be a time series. Each product may have some amount available at the beginning of each time period. In this case, the key initial amounts maps to a dictionary with the following keys: Key Description latitude (deg) The latitude of the location. longitude (deg) The longitude of the location. amount (tonne) The amount of the product initially available at the location. Must be a time series.","title":"Products"},{"location":"format/#example_1","text":"{ \"products\": { \"P1\": { \"initial amounts\": { \"C1\": { \"latitude (deg)\": 7.0, \"longitude (deg)\": 7.0, \"amount (tonne)\": [934.56, 934.56] }, \"C2\": { \"latitude (deg)\": 7.0, \"longitude (deg)\": 19.0, \"amount (tonne)\": [198.95, 198.95] }, \"C3\": { \"latitude (deg)\": 84.0, \"longitude (deg)\": 76.0, \"amount (tonne)\": [212.97, 212.97] } }, \"transportation cost ($/km/tonne)\": [0.015, 0.015], \"transportation energy (J/km/tonne)\": [0.12, 0.11], \"transportation emissions (tonne/km/tonne)\": { \"CO2\": [0.052, 0.050], \"CH4\": [0.003, 0.002] } }, \"P2\": { \"transportation cost ($/km/tonne)\": [0.022, 0.020] }, \"P3\": { \"transportation cost ($/km/tonne)\": [0.0125, 0.0125] }, \"P4\": { \"transportation cost ($/km/tonne)\": [0.0175, 0.0175] } } }","title":"Example"},{"location":"format/#processing-plants","text":"The plants section describes the available types of reverse manufacturing plants, their potential locations and associated costs, as well as their inputs and outputs. The field instance[\"Plants\"] is a dictionary mapping the name of the plant to a dictionary with the following keys: Key Description input The name of the product that this plant takes as input. Only one input is accepted per plant. outputs (tonne/tonne) A dictionary specifying how many tonnes of each product is produced for each tonnes of input. For example, if the plant outputs 0.5 tonnes of P2 and 0.25 tonnes of P3 for each tonnes of P1 provided, then this entry should be {\"P2\": 0.5, \"P3\": 0.25} . If the plant does not output anything, this key may be omitted. energy (GJ/tonne) The energy required to process 1 tonne of the input. Must be a time series. Optional. emissions (tonne/tonne) A dictionary mapping the name of each greenhouse gas, produced to process each tonne of input, to the amount of gas produced (in tonne). Must be a time series. Optional. locations A dictionary mapping the name of the location to a dictionary which describes the site characteristics (see below). Each type of plant is associated with a set of potential locations where it can be built. Each location is represented by a dictionary with the following keys: Key Description latitude (deg) The latitude of the location, in degrees. longitude (deg) The longitude of the location, in degrees. disposal A dictionary describing what products can be disposed locally at the plant. capacities (tonne) A dictionary describing what plant sizes are allowed, and their characteristics. The keys in the disposal dictionary should be the names of the products. The values are dictionaries with the following keys: Key Description cost ($/tonne) The cost to dispose of the product. Must be a time series. limit (tonne) The maximum amount that can be disposed of. If an unlimited amount can be disposed, this key may be omitted. Must be a time series. The keys in the capacities (tonne) dictionary should be the amounts (in tonnes). The values are dictionaries with the following keys: Key Description opening cost ($) The cost to open a plant of this size. fixed operating cost ($) The cost to keep the plant open, even if the plant doesn't process anything. Must be a time series. variable operating cost ($/tonne) The cost that the plant incurs to process each tonne of input. Must be a time series.","title":"Processing plants"},{"location":"format/#example_2","text":"{ \"plants\": { \"F1\": { \"input\": \"P1\", \"outputs (tonne/tonne)\": { \"P2\": 0.2, \"P3\": 0.5 }, \"energy (GJ/tonne)\": [0.12, 0.11], \"emissions (tonne/tonne)\": { \"CO2\": [0.052, 0.050], \"CH4\": [0.003, 0.002] }, \"locations\": { \"L1\": { \"latitude (deg)\": 0.0, \"longitude (deg)\": 0.0, \"disposal\": { \"P2\": { \"cost ($/tonne)\": [-10.0, -12.0], \"limit (tonne)\": [1.0, 1.0] } }, \"capacities (tonne)\": { \"100\": { \"opening cost ($)\": [500, 530], \"fixed operating cost ($)\": [300.0, 310.0], \"variable operating cost ($/tonne)\": [5.0, 5.2] }, \"500\": { \"opening cost ($)\": [750, 760], \"fixed operating cost ($)\": [400.0, 450.0], \"variable operating cost ($/tonne)\": [5.0, 5.2] } } } } } } }","title":"Example"},{"location":"format/#current-limitations","text":"Each plant can only be opened exactly once. After open, the plant remains open until the end of the simulation. Plants can be expanded at any time, even long after they are open. All material available at the beginning of a time period must be entirely processed by the end of that time period. It is not possible to store unprocessed materials from one time period to the next. Up to two plant sizes are currently supported. Variable operating costs must be the same for all plant sizes.","title":"Current limitations"},{"location":"format/#output-data-format-json","text":"To be documented.","title":"Output Data Format (JSON)"},{"location":"model/","text":"Optimization Model In this page, we describe the precise mathematical optimization model used by RELOG to find the optimal logistics plan. This model is a variation of the classical Facility Location Problem, which has been widely studied in the operations research literature. To simplify the exposition, we present the simplified case where there is only one type of plant. Mathematical Description Sets $L$ - Set of locations holding the original material to be recycled $M$ - Set of materials recovered during the reverse manufacturing process $P$ - Set of potential plants to open $T = { 1, \\ldots, t^{max} } $ - Set of time periods Constants Plants: $c^\\text{disp}_{pmt}$ - Cost of disposing one tonne of material $m$ at plant $p$ during time $t$ ( $/tonne/km ) $c^\\text{exp}_{pt}$ - Cost of adding one tonne of capacity to plant $p$ at time $t$ ( $/tonne ) $c^\\text{open}_{pt}$ - Cost of opening plant $p$ at time $t$, at minimum capacity ( $ ) $c^\\text{f-base}_{pt}$ - Fixed cost of keeping plant $p$ open during time period $t$ ( $ ) $c^\\text{f-exp}_{pt}$ - Increase in fixed cost for each additional tonne of capacity ( $/tonne ) $c^\\text{var}_{pt}$ - Variable cost of processing one tonne of input at plant $p$ at time $t$ ( $/tonne ) $m^\\text{min}_p$ - Minimum capacity of plant $p$ ( tonne ) $m^\\text{max}_p$ - Maximum capacity of plant $p$ ( tonne ) $m^\\text{disp}_{pmt}$ - Maximum amount of material $m$ that plant $p$ can dispose of during time $t$ ( tonne ) Products: $\\alpha_{pm}$ - Amount of material $m$ recovered by plant $t$ for each tonne of original material ( tonne/tonne ) $m^\\text{initial}_{lt}$ - Amount of original material to be recycled at location $l$ during time $t$ ( tonne ) Transportation: $c^\\text{tr}_{t}$ - Transportation cost during time $t$ ( $/tonne/km ) $d_{lp}$ - Distance between plant $p$ and location $l$ ( km ) Decision variables $q_{mpt}$ - Amount of material $m$ recovered by plant $p$ during time $t$ ( tonne ) $u_{pt}$ - Binary variable that equals 1 if plant $p$ starts operating at time $t$ ( bool ) $w_{pt}$ - Extra capacity (amount above the minimum) added to plant $p$ during time $t$ ( tonne ) $x_{pt}$ - Binary variable that equals 1 if plant $p$ is operational at time $t$ ( bool ) $y_{lpt}$ - Amount of product sent from location $l$ to plant $p$ during time $t$ ( tonne ) $z_{mpt}$ - Amount of material $m$ disposed of by plant $p$ during time $t$ ( tonne ) Objective function RELOG minimizes the overall capital, production and transportation costs: \\begin{align*} \\text{minimize} \\;\\; & \\sum_{t \\in T} \\sum_{p \\in P} \\left[ c^\\text{open}_{pt} u_{pt} + c^\\text{f-base}_{pt} x_{pt} + \\sum_{i=1}^t c^\\text{f-exp}_{pt} w_{pi} + c^{\\text{exp}}_{pt} w_{pt} \\right] + \\\\ & \\sum_{t \\in T} \\sum_{l \\in L} \\sum_{p \\in P} \\left[ c^{\\text{tr}}_t d_{lp} + c^{\\text{var}}_{pt} \\right] y_{lpt} + \\\\ & \\sum_{t \\in T} \\sum_{p \\in P} \\sum_{m \\in M} c^{\\text{disp}}_{pmt} z_{pmt} \\end{align*} In the first line, we have (i) opening costs, if plant starts operating at time $t$, (ii) fixed operating costs, if plant is operational, (iii) additional fixed operating costs coming from expansion performed in all previous time periods up to the current one, and finally (iv) the expansion costs during the current time period. In the second line, we have the transportation costs and the variable operating costs. In the third line, we have the disposal costs. Constraints All original materials must be sent to a plant: \\begin{align} & \\sum_{p \\in P} y_{lpt} = m^\\text{initial}_{lt} & \\forall l \\in L, t \\in T \\end{align} Plants have a limited capacity: \\begin{align} & \\sum_{l \\in L} y_{lpt} \\leq m^\\text{min}_p x_p + \\sum_{i=1}^t w_p & \\forall p \\in P, t \\in T \\end{align} Plants can only be expanded up to their maximum capacity. Furthermore, if a plant is closed, it cannot be expanded: \\begin{align} & \\sum_{i=1}^t w_p \\leq m^\\text{max}_p x_p & \\forall p \\in P, t \\in T \\end{align} Amount of recovered material is proportional to the plant input: \\begin{align} & q_{mpt} = \\alpha_{pm} \\sum_{l \\in L} y_{lpt} & \\forall m \\in M, p \\in P, t \\in T \\end{align} Because we only consider a single type of plant, all recovered material must be immediately disposed of. In RELOG's full model, recovered materials may be sent to another plant for further processing. \\begin{align} & q_{mpt} = z_{mpt} & \\forall m \\in M, p \\in P, t \\in T \\end{align} A plant is operational at time $t$ if it was operational at time $t-1$ or it was built at time $t$. This constraint also prevents a plant from being built multiple times. \\begin{align} & x_{pt} = x_{p,t-1} + u_{pt} & \\forall p \\in P, t \\in T \\setminus \\{1\\} \\\\ & x_{p,1} = u_{p,1} & \\forall p \\in P \\end{align} Variable bounds: \\begin{align} & q_{mpt} \\geq 0 & \\forall m \\in M, p \\in P, t \\in T \\\\ & u_{pt} \\in \\{0,1\\} & \\forall p \\in P, t \\in T \\\\ & w_{pt} \\geq 0 & \\forall p \\in P, t \\in T \\\\ & x_{pt} \\in \\{0,1\\} & \\forall p \\in P, t \\in T \\\\ & y_{lpt} \\geq 0 & \\forall l \\in L, p \\in P, t \\in T \\\\ & m^\\text{disp}_{mpt} \\geq z_{mpt} \\geq 0 & \\forall m \\in M, p \\in P, t \\in T \\end{align} Complete optimization model \\begin{align*} \\text{minimize} \\;\\; & \\sum_{t \\in T} \\sum_{p \\in P} \\left[ c^\\text{open}_{pt} u_{pt} + c^\\text{f-base}_{pt} x_{pt} + \\sum_{i=1}^t c^\\text{f-exp}_{pt} w_{pi} + c^{\\text{exp}}_{pt} w_{pt} \\right] + \\\\ & \\sum_{t \\in T} \\sum_{l \\in L} \\sum_{p \\in P} \\left[ c^{\\text{tr}}_t d_{lp} + c^{\\text{var}}_{pt} \\right] y_{lpt} + \\\\ & \\sum_{t \\in T} \\sum_{p \\in P} \\sum_{m \\in M} c^{\\text{disp}}_{pmt} z_{pmt} \\\\ \\text{subject to } & \\sum_{p \\in P} y_{lpt} = m^\\text{initial}_{lt} & \\forall l \\in L, t \\in T \\\\ & \\sum_{l \\in L} y_{lpt} \\leq m^\\text{min}_p x_p + \\sum_{i=1}^t w_p & \\forall p \\in P, t \\in T \\\\ & \\sum_{i=1}^t w_p \\leq m^\\text{max}_p x_p & \\forall p \\in P, t \\in T \\\\ & q_{mpt} = \\alpha_{pm} \\sum_{l \\in L} y_{lpt} & \\forall m \\in M, p \\in P, t \\in T \\\\ & q_{mpt} = z_{mpt} & \\forall m \\in M, p \\in P, t \\in T \\\\ & x_{pt} = x_{p,t-1} + u_{pt} & \\forall p \\in P, t \\in T \\setminus \\{1\\} \\\\ & x_{p,1} = u_{p,1} & \\forall p \\in P \\\\ & q_{mpt} \\geq 0 & \\forall m \\in M, p \\in P, t \\in T \\\\ & u_{pt} \\in \\{0,1\\} & \\forall p \\in P, t \\in T \\\\ & w_{pt} \\geq 0 & \\forall p \\in P, t \\in T \\\\ & x_{pt} \\in \\{0,1\\} & \\forall p \\in P, t \\in T \\\\ & y_{lpt} \\geq 0 & \\forall l \\in L, p \\in P, t \\in T \\\\ & m^\\text{disp}_{mpt} \\geq z_{mpt} \\geq 0 & \\forall m \\in M, p \\in P, t \\in T \\end{align*}","title":"Optimization Model"},{"location":"model/#optimization-model","text":"In this page, we describe the precise mathematical optimization model used by RELOG to find the optimal logistics plan. This model is a variation of the classical Facility Location Problem, which has been widely studied in the operations research literature. To simplify the exposition, we present the simplified case where there is only one type of plant.","title":"Optimization Model"},{"location":"model/#mathematical-description","text":"","title":"Mathematical Description"},{"location":"model/#sets","text":"$L$ - Set of locations holding the original material to be recycled $M$ - Set of materials recovered during the reverse manufacturing process $P$ - Set of potential plants to open $T = { 1, \\ldots, t^{max} } $ - Set of time periods","title":"Sets"},{"location":"model/#constants","text":"Plants: $c^\\text{disp}_{pmt}$ - Cost of disposing one tonne of material $m$ at plant $p$ during time $t$ ( $/tonne/km ) $c^\\text{exp}_{pt}$ - Cost of adding one tonne of capacity to plant $p$ at time $t$ ( $/tonne ) $c^\\text{open}_{pt}$ - Cost of opening plant $p$ at time $t$, at minimum capacity ( $ ) $c^\\text{f-base}_{pt}$ - Fixed cost of keeping plant $p$ open during time period $t$ ( $ ) $c^\\text{f-exp}_{pt}$ - Increase in fixed cost for each additional tonne of capacity ( $/tonne ) $c^\\text{var}_{pt}$ - Variable cost of processing one tonne of input at plant $p$ at time $t$ ( $/tonne ) $m^\\text{min}_p$ - Minimum capacity of plant $p$ ( tonne ) $m^\\text{max}_p$ - Maximum capacity of plant $p$ ( tonne ) $m^\\text{disp}_{pmt}$ - Maximum amount of material $m$ that plant $p$ can dispose of during time $t$ ( tonne ) Products: $\\alpha_{pm}$ - Amount of material $m$ recovered by plant $t$ for each tonne of original material ( tonne/tonne ) $m^\\text{initial}_{lt}$ - Amount of original material to be recycled at location $l$ during time $t$ ( tonne ) Transportation: $c^\\text{tr}_{t}$ - Transportation cost during time $t$ ( $/tonne/km ) $d_{lp}$ - Distance between plant $p$ and location $l$ ( km )","title":"Constants"},{"location":"model/#decision-variables","text":"$q_{mpt}$ - Amount of material $m$ recovered by plant $p$ during time $t$ ( tonne ) $u_{pt}$ - Binary variable that equals 1 if plant $p$ starts operating at time $t$ ( bool ) $w_{pt}$ - Extra capacity (amount above the minimum) added to plant $p$ during time $t$ ( tonne ) $x_{pt}$ - Binary variable that equals 1 if plant $p$ is operational at time $t$ ( bool ) $y_{lpt}$ - Amount of product sent from location $l$ to plant $p$ during time $t$ ( tonne ) $z_{mpt}$ - Amount of material $m$ disposed of by plant $p$ during time $t$ ( tonne )","title":"Decision variables"},{"location":"model/#objective-function","text":"RELOG minimizes the overall capital, production and transportation costs: \\begin{align*} \\text{minimize} \\;\\; & \\sum_{t \\in T} \\sum_{p \\in P} \\left[ c^\\text{open}_{pt} u_{pt} + c^\\text{f-base}_{pt} x_{pt} + \\sum_{i=1}^t c^\\text{f-exp}_{pt} w_{pi} + c^{\\text{exp}}_{pt} w_{pt} \\right] + \\\\ & \\sum_{t \\in T} \\sum_{l \\in L} \\sum_{p \\in P} \\left[ c^{\\text{tr}}_t d_{lp} + c^{\\text{var}}_{pt} \\right] y_{lpt} + \\\\ & \\sum_{t \\in T} \\sum_{p \\in P} \\sum_{m \\in M} c^{\\text{disp}}_{pmt} z_{pmt} \\end{align*} In the first line, we have (i) opening costs, if plant starts operating at time $t$, (ii) fixed operating costs, if plant is operational, (iii) additional fixed operating costs coming from expansion performed in all previous time periods up to the current one, and finally (iv) the expansion costs during the current time period. In the second line, we have the transportation costs and the variable operating costs. In the third line, we have the disposal costs.","title":"Objective function"},{"location":"model/#constraints","text":"All original materials must be sent to a plant: \\begin{align} & \\sum_{p \\in P} y_{lpt} = m^\\text{initial}_{lt} & \\forall l \\in L, t \\in T \\end{align} Plants have a limited capacity: \\begin{align} & \\sum_{l \\in L} y_{lpt} \\leq m^\\text{min}_p x_p + \\sum_{i=1}^t w_p & \\forall p \\in P, t \\in T \\end{align} Plants can only be expanded up to their maximum capacity. Furthermore, if a plant is closed, it cannot be expanded: \\begin{align} & \\sum_{i=1}^t w_p \\leq m^\\text{max}_p x_p & \\forall p \\in P, t \\in T \\end{align} Amount of recovered material is proportional to the plant input: \\begin{align} & q_{mpt} = \\alpha_{pm} \\sum_{l \\in L} y_{lpt} & \\forall m \\in M, p \\in P, t \\in T \\end{align} Because we only consider a single type of plant, all recovered material must be immediately disposed of. In RELOG's full model, recovered materials may be sent to another plant for further processing. \\begin{align} & q_{mpt} = z_{mpt} & \\forall m \\in M, p \\in P, t \\in T \\end{align} A plant is operational at time $t$ if it was operational at time $t-1$ or it was built at time $t$. This constraint also prevents a plant from being built multiple times. \\begin{align} & x_{pt} = x_{p,t-1} + u_{pt} & \\forall p \\in P, t \\in T \\setminus \\{1\\} \\\\ & x_{p,1} = u_{p,1} & \\forall p \\in P \\end{align} Variable bounds: \\begin{align} & q_{mpt} \\geq 0 & \\forall m \\in M, p \\in P, t \\in T \\\\ & u_{pt} \\in \\{0,1\\} & \\forall p \\in P, t \\in T \\\\ & w_{pt} \\geq 0 & \\forall p \\in P, t \\in T \\\\ & x_{pt} \\in \\{0,1\\} & \\forall p \\in P, t \\in T \\\\ & y_{lpt} \\geq 0 & \\forall l \\in L, p \\in P, t \\in T \\\\ & m^\\text{disp}_{mpt} \\geq z_{mpt} \\geq 0 & \\forall m \\in M, p \\in P, t \\in T \\end{align}","title":"Constraints"},{"location":"model/#complete-optimization-model","text":"\\begin{align*} \\text{minimize} \\;\\; & \\sum_{t \\in T} \\sum_{p \\in P} \\left[ c^\\text{open}_{pt} u_{pt} + c^\\text{f-base}_{pt} x_{pt} + \\sum_{i=1}^t c^\\text{f-exp}_{pt} w_{pi} + c^{\\text{exp}}_{pt} w_{pt} \\right] + \\\\ & \\sum_{t \\in T} \\sum_{l \\in L} \\sum_{p \\in P} \\left[ c^{\\text{tr}}_t d_{lp} + c^{\\text{var}}_{pt} \\right] y_{lpt} + \\\\ & \\sum_{t \\in T} \\sum_{p \\in P} \\sum_{m \\in M} c^{\\text{disp}}_{pmt} z_{pmt} \\\\ \\text{subject to } & \\sum_{p \\in P} y_{lpt} = m^\\text{initial}_{lt} & \\forall l \\in L, t \\in T \\\\ & \\sum_{l \\in L} y_{lpt} \\leq m^\\text{min}_p x_p + \\sum_{i=1}^t w_p & \\forall p \\in P, t \\in T \\\\ & \\sum_{i=1}^t w_p \\leq m^\\text{max}_p x_p & \\forall p \\in P, t \\in T \\\\ & q_{mpt} = \\alpha_{pm} \\sum_{l \\in L} y_{lpt} & \\forall m \\in M, p \\in P, t \\in T \\\\ & q_{mpt} = z_{mpt} & \\forall m \\in M, p \\in P, t \\in T \\\\ & x_{pt} = x_{p,t-1} + u_{pt} & \\forall p \\in P, t \\in T \\setminus \\{1\\} \\\\ & x_{p,1} = u_{p,1} & \\forall p \\in P \\\\ & q_{mpt} \\geq 0 & \\forall m \\in M, p \\in P, t \\in T \\\\ & u_{pt} \\in \\{0,1\\} & \\forall p \\in P, t \\in T \\\\ & w_{pt} \\geq 0 & \\forall p \\in P, t \\in T \\\\ & x_{pt} \\in \\{0,1\\} & \\forall p \\in P, t \\in T \\\\ & y_{lpt} \\geq 0 & \\forall l \\in L, p \\in P, t \\in T \\\\ & m^\\text{disp}_{mpt} \\geq z_{mpt} \\geq 0 & \\forall m \\in M, p \\in P, t \\in T \\end{align*}","title":"Complete optimization model"},{"location":"reports/","text":"Simplified Solution Reports In addition to the full output format described in data formats , RELOG can also generate a number of simplified reports in tabular data format (CSV), which can be more easily processed by spreadsheet software (such as Microsoft Excel), by data analysis libraries (such as Pandas) or by relational databases (such as SQLite). In this page, we also illustrate what types of charts and visualizations can be produced from these tabular data files. The sample charts have been produced using Python, matplotlib, seaborn and geopandas. Plants report Report showing plant costs, capacities, energy expenditure and utilization factors. Generated by RELOG.write_plants_report(solution, filename) . For a concrete example, see nimh_plants.csv . Column Description plant type Plant type. location name Location name. year What year this row corresponds to. This reports includes one row for each year in the simulation. latitude (deg) Latitude of the plant. longitude (deg) Longitude of the plant. capacity (tonne) Capacity of the plant at this point in time. amount processed (tonne) Amount of input material received by the plant this year. utilization factor (%) Amount processed by the plant this year divided by current plant capacity. energy (GJ) Amount of energy expended by the plant this year. opening cost ($) Amount spent opening the plant. This value is only positive if the plant became operational this year. expansion cost ($) Amount spent this year expanding the plant capacity. fixed operating cost ($) Amount spent for keeping the plant operational this year. variable operating cost ($) Amount spent for processing the input material this year. total cost ($) Sum of all previous plant costs. Sample charts Bar plot with total plant costs per year, grouped by plant type (in Python): import pandas as pd import seaborn as sns; sns.set() data = pd.read_csv(\"plants_report.csv\") sns.barplot(x=\"year\", y=\"total cost ($)\", hue=\"plant type\", data=data.groupby([\"plant type\", \"year\"]) .sum() .reset_index()); Map showing plant locations (in Python): import pandas as pd import geopandas as gp # Plot base map world = gp.read_file(gp.datasets.get_path('naturalearth_lowres')) ax = world.plot(color='white', edgecolor='50', figsize=(13,6)) ax.set_ylim([23, 50]) ax.set_xlim([-128, -65]) # Plot plant locations data = pd.read_csv(\"nimh_plants.csv\") points = gp.points_from_xy(data[\"longitude (deg)\"], data[\"latitude (deg)\"]) gp.GeoDataFrame(data, geometry=points).plot(ax=ax); Plant outputs report Report showing amount of products produced, sent and disposed of by each plant, as well as disposal costs. Generated by RELOG.write_plant_outputs_report(solution, filename) . For a concrete example, see nimh_plant_outputs.csv . Column Description plant type Plant type. location name Location name. year What year this row corresponds to. This reports includes one row for each year in the simulation. product name Product being produced. amount produced (tonne) Amount of product produced this year. amount sent (tonne) Amount of product produced by this plant and sent to another plant for further processing this year. amount disposed (tonne) Amount produced produced by this plant and immediately disposed of locally this year. disposal cost ($) Disposal cost for this year. Sample charts Bar plot showing total amount produced for each product, grouped by year (in Python): import pandas as pd import seaborn as sns; sns.set() data = pd.read_csv(\"plant_outputs_report.csv\") sns.barplot(x=\"amount produced (tonne)\", y=\"product name\", hue=\"year\", data=data.groupby([\"product name\", \"year\"]) .sum() .reset_index()); Plant emissions report Report showing amount of emissions produced by each plant. Generated by RELOG.write_plant_emissions_report(solution, filename) . For a concrete example, see nimh_plant_emissions.csv . Column Description plant type Plant type. location name Location name. year Year. emission type Type of emission. amount (tonne) Amount of emission produced by the plant this year. Sample charts Bar plot showing total emission by plant type, grouped type of emissions (in Python): import pandas as pd import seaborn as sns; sns.set() data = pd.read_csv(\"plant_emissions_report.csv\") sns.barplot(x=\"plant type\", y=\"emission amount (tonne)\", hue=\"emission type\", data=data.groupby([\"plant type\", \"emission type\"]) .sum() .reset_index()); Transportation report Report showing amount of product sent from initial locations to plants, and from one plant to another. Includes the distance between each pair of locations, amount-distance shipped, transportation costs and energy expenditure. Generated by RELOG.write_transportation_report(solution, filename) . For a concrete example, see nimh_transportation.csv . Column Description source type If product is being shipped from an initial location, equals Origin . If product is being shipped from a plant, equals plant type. source location name Name of the location where the product is being shipped from. source latitude (deg) Latitude of the source location. source longitude (deg) Longitude of the source location. destination type Type of plant the product is being shipped to. destination location name Name of the location where the product is being shipped to. destination latitude (deg) Latitude of the destination location. destination longitude (deg) Longitude of the destination location. product Product being shipped. year Year. distance (km) Distance between source and destination. amount (tonne) Total amount of product being shipped between the two locations this year. amount-distance (tonne-km) Total amount being shipped this year times distance. transportation cost ($) Cost to transport this amount of product between the two locations for this year. transportation energy (GJ) Energy expended transporting this amount of product between the two locations. Sample charts Bar plot showing total amount-distance for each product type, grouped by year (in Python): import pandas as pd import seaborn as sns; sns.set() data = pd.read_csv(\"transportation_report.csv\") sns.barplot(x=\"product\", y=\"amount-distance (tonne-km)\", hue=\"year\", data=data.groupby([\"product\", \"year\"]) .sum() .reset_index()); Map of transportation lines (in Python): import pandas as pd import geopandas as gp from shapely.geometry import Point, LineString import matplotlib.pyplot as plt from matplotlib import collections # Plot base map world = gp.read_file(gp.datasets.get_path('naturalearth_lowres')) ax = world.plot(color='white', edgecolor='50', figsize=(14,7)) ax.set_ylim([23, 50]) ax.set_xlim([-128, -65]) # Draw transportation lines data = pd.read_csv(\"transportation_report.csv\") lines = [[(row[\"source longitude (deg)\"], row[\"source latitude (deg)\"]), (row[\"destination longitude (deg)\"], row[\"destination latitude (deg)\"]) ] for (index, row) in data.iterrows()] ax.add_collection(collections.LineCollection(lines, linewidths=0.25, zorder=1, alpha=0.5, color=\"50\")) # Draw source points points = gp.points_from_xy(data[\"source longitude (deg)\"], data[\"source latitude (deg)\"]) gp.GeoDataFrame(data, geometry=points).plot(ax=ax, color=\"0.5\", markersize=1); # Draw destination points points = gp.points_from_xy(data[\"destination longitude (deg)\"], data[\"destination latitude (deg)\"]) gp.GeoDataFrame(data, geometry=points).plot(ax=ax, color=\"red\", markersize=50); Transportation emissions report Report showing emissions for each trip between initial locations and plants, and between pairs of plants. Generated by RELOG.write_transportation_emissions_report(solution, filename) . For a concrete example, see nimh_transportation_emissions.csv . Column Description source type If product is being shipped from an initial location, equals Origin . If product is being shipped from a plant, equals plant type. source location name Name of the location where the product is being shipped from. source latitude (deg) Latitude of the source location. source longitude (deg) Longitude of the source location. destination type Type of plant the product is being shipped to. destination location name Name of the location where the product is being shipped to. destination latitude (deg) Latitude of the destination location. destination longitude (deg) Longitude of the destination location. product Product being shipped. year Year. distance (km) Distance between source and destination. shipped amount (tonne) Total amount of product being shipped between the two locations this year. shipped amount-distance (tonne-km) Total amount being shipped this year times distance. emission type Type of emission. emission amount (tonne) Amount of emission produced by transportation segment this year. Sample charts Bar plot showing total emission amount by emission type, grouped by type of product being transported (in Python): import pandas as pd import seaborn as sns; sns.set() data = pd.read_csv(\"transportation_emissions_report.csv\") sns.barplot(x=\"emission type\", y=\"emission amount (tonne)\", hue=\"product\", data=data.groupby([\"product\", \"emission type\"]) .sum() .reset_index());","title":"Reports"},{"location":"reports/#simplified-solution-reports","text":"In addition to the full output format described in data formats , RELOG can also generate a number of simplified reports in tabular data format (CSV), which can be more easily processed by spreadsheet software (such as Microsoft Excel), by data analysis libraries (such as Pandas) or by relational databases (such as SQLite). In this page, we also illustrate what types of charts and visualizations can be produced from these tabular data files. The sample charts have been produced using Python, matplotlib, seaborn and geopandas.","title":"Simplified Solution Reports"},{"location":"reports/#plants-report","text":"Report showing plant costs, capacities, energy expenditure and utilization factors. Generated by RELOG.write_plants_report(solution, filename) . For a concrete example, see nimh_plants.csv . Column Description plant type Plant type. location name Location name. year What year this row corresponds to. This reports includes one row for each year in the simulation. latitude (deg) Latitude of the plant. longitude (deg) Longitude of the plant. capacity (tonne) Capacity of the plant at this point in time. amount processed (tonne) Amount of input material received by the plant this year. utilization factor (%) Amount processed by the plant this year divided by current plant capacity. energy (GJ) Amount of energy expended by the plant this year. opening cost ($) Amount spent opening the plant. This value is only positive if the plant became operational this year. expansion cost ($) Amount spent this year expanding the plant capacity. fixed operating cost ($) Amount spent for keeping the plant operational this year. variable operating cost ($) Amount spent for processing the input material this year. total cost ($) Sum of all previous plant costs.","title":"Plants report"},{"location":"reports/#sample-charts","text":"Bar plot with total plant costs per year, grouped by plant type (in Python): import pandas as pd import seaborn as sns; sns.set() data = pd.read_csv(\"plants_report.csv\") sns.barplot(x=\"year\", y=\"total cost ($)\", hue=\"plant type\", data=data.groupby([\"plant type\", \"year\"]) .sum() .reset_index()); Map showing plant locations (in Python): import pandas as pd import geopandas as gp # Plot base map world = gp.read_file(gp.datasets.get_path('naturalearth_lowres')) ax = world.plot(color='white', edgecolor='50', figsize=(13,6)) ax.set_ylim([23, 50]) ax.set_xlim([-128, -65]) # Plot plant locations data = pd.read_csv(\"nimh_plants.csv\") points = gp.points_from_xy(data[\"longitude (deg)\"], data[\"latitude (deg)\"]) gp.GeoDataFrame(data, geometry=points).plot(ax=ax);","title":"Sample charts"},{"location":"reports/#plant-outputs-report","text":"Report showing amount of products produced, sent and disposed of by each plant, as well as disposal costs. Generated by RELOG.write_plant_outputs_report(solution, filename) . For a concrete example, see nimh_plant_outputs.csv . Column Description plant type Plant type. location name Location name. year What year this row corresponds to. This reports includes one row for each year in the simulation. product name Product being produced. amount produced (tonne) Amount of product produced this year. amount sent (tonne) Amount of product produced by this plant and sent to another plant for further processing this year. amount disposed (tonne) Amount produced produced by this plant and immediately disposed of locally this year. disposal cost ($) Disposal cost for this year.","title":"Plant outputs report"},{"location":"reports/#sample-charts_1","text":"Bar plot showing total amount produced for each product, grouped by year (in Python): import pandas as pd import seaborn as sns; sns.set() data = pd.read_csv(\"plant_outputs_report.csv\") sns.barplot(x=\"amount produced (tonne)\", y=\"product name\", hue=\"year\", data=data.groupby([\"product name\", \"year\"]) .sum() .reset_index());","title":"Sample charts"},{"location":"reports/#plant-emissions-report","text":"Report showing amount of emissions produced by each plant. Generated by RELOG.write_plant_emissions_report(solution, filename) . For a concrete example, see nimh_plant_emissions.csv . Column Description plant type Plant type. location name Location name. year Year. emission type Type of emission. amount (tonne) Amount of emission produced by the plant this year.","title":"Plant emissions report"},{"location":"reports/#sample-charts_2","text":"Bar plot showing total emission by plant type, grouped type of emissions (in Python): import pandas as pd import seaborn as sns; sns.set() data = pd.read_csv(\"plant_emissions_report.csv\") sns.barplot(x=\"plant type\", y=\"emission amount (tonne)\", hue=\"emission type\", data=data.groupby([\"plant type\", \"emission type\"]) .sum() .reset_index());","title":"Sample charts"},{"location":"reports/#transportation-report","text":"Report showing amount of product sent from initial locations to plants, and from one plant to another. Includes the distance between each pair of locations, amount-distance shipped, transportation costs and energy expenditure. Generated by RELOG.write_transportation_report(solution, filename) . For a concrete example, see nimh_transportation.csv . Column Description source type If product is being shipped from an initial location, equals Origin . If product is being shipped from a plant, equals plant type. source location name Name of the location where the product is being shipped from. source latitude (deg) Latitude of the source location. source longitude (deg) Longitude of the source location. destination type Type of plant the product is being shipped to. destination location name Name of the location where the product is being shipped to. destination latitude (deg) Latitude of the destination location. destination longitude (deg) Longitude of the destination location. product Product being shipped. year Year. distance (km) Distance between source and destination. amount (tonne) Total amount of product being shipped between the two locations this year. amount-distance (tonne-km) Total amount being shipped this year times distance. transportation cost ($) Cost to transport this amount of product between the two locations for this year. transportation energy (GJ) Energy expended transporting this amount of product between the two locations.","title":"Transportation report"},{"location":"reports/#sample-charts_3","text":"Bar plot showing total amount-distance for each product type, grouped by year (in Python): import pandas as pd import seaborn as sns; sns.set() data = pd.read_csv(\"transportation_report.csv\") sns.barplot(x=\"product\", y=\"amount-distance (tonne-km)\", hue=\"year\", data=data.groupby([\"product\", \"year\"]) .sum() .reset_index()); Map of transportation lines (in Python): import pandas as pd import geopandas as gp from shapely.geometry import Point, LineString import matplotlib.pyplot as plt from matplotlib import collections # Plot base map world = gp.read_file(gp.datasets.get_path('naturalearth_lowres')) ax = world.plot(color='white', edgecolor='50', figsize=(14,7)) ax.set_ylim([23, 50]) ax.set_xlim([-128, -65]) # Draw transportation lines data = pd.read_csv(\"transportation_report.csv\") lines = [[(row[\"source longitude (deg)\"], row[\"source latitude (deg)\"]), (row[\"destination longitude (deg)\"], row[\"destination latitude (deg)\"]) ] for (index, row) in data.iterrows()] ax.add_collection(collections.LineCollection(lines, linewidths=0.25, zorder=1, alpha=0.5, color=\"50\")) # Draw source points points = gp.points_from_xy(data[\"source longitude (deg)\"], data[\"source latitude (deg)\"]) gp.GeoDataFrame(data, geometry=points).plot(ax=ax, color=\"0.5\", markersize=1); # Draw destination points points = gp.points_from_xy(data[\"destination longitude (deg)\"], data[\"destination latitude (deg)\"]) gp.GeoDataFrame(data, geometry=points).plot(ax=ax, color=\"red\", markersize=50);","title":"Sample charts"},{"location":"reports/#transportation-emissions-report","text":"Report showing emissions for each trip between initial locations and plants, and between pairs of plants. Generated by RELOG.write_transportation_emissions_report(solution, filename) . For a concrete example, see nimh_transportation_emissions.csv . Column Description source type If product is being shipped from an initial location, equals Origin . If product is being shipped from a plant, equals plant type. source location name Name of the location where the product is being shipped from. source latitude (deg) Latitude of the source location. source longitude (deg) Longitude of the source location. destination type Type of plant the product is being shipped to. destination location name Name of the location where the product is being shipped to. destination latitude (deg) Latitude of the destination location. destination longitude (deg) Longitude of the destination location. product Product being shipped. year Year. distance (km) Distance between source and destination. shipped amount (tonne) Total amount of product being shipped between the two locations this year. shipped amount-distance (tonne-km) Total amount being shipped this year times distance. emission type Type of emission. emission amount (tonne) Amount of emission produced by transportation segment this year.","title":"Transportation emissions report"},{"location":"reports/#sample-charts_4","text":"Bar plot showing total emission amount by emission type, grouped by type of product being transported (in Python): import pandas as pd import seaborn as sns; sns.set() data = pd.read_csv(\"transportation_emissions_report.csv\") sns.barplot(x=\"emission type\", y=\"emission amount (tonne)\", hue=\"product\", data=data.groupby([\"product\", \"emission type\"]) .sum() .reset_index());","title":"Sample charts"},{"location":"usage/","text":"Usage 1. Installation To use RELOG, the first step is to install the Julia programming language on your machine. Note that RELOG was developed and tested with Julia 1.5 and may not be compatible with newer versions. After Julia is installed, launch the Julia console, type ] to switch to package manger mode, then run: (@v1.5) pkg> add https://github.com/ANL-CEEESA/RELOG.git After the package and all its dependencies have been installed, please run the RELOG test suite, as shown below, to make sure that the package has been correctly installed: (@v1.5) pkg> test RELOG To update the package to a newer version, type ] to enter the package manager mode, then run: (@v1.5) pkg> update RELOG 2. Modeling the problem The two main model components in RELOG are products and plants . A product is any material that needs to be recycled, any intermediary product produced during the recycling process, or any product recovered at the end of the process. For example, in a NiMH battery recycling study case, products could include (i) the original batteries to be recycled; (ii) the cathode and anode parts of the battery; (iii) rare-earth elements and (iv) scrap metals. The model assumes that some products are initially available at user-specified locations (described by their latitude, longitude and the amount available), while other products only become available during the recycling process. Transporting products from one location to another incurs a transportation cost ( $/km/tonne ), spends some amount of energy ( J/km/tonne ) and may generate multiple types of emissions ( tonne/tonne ). All these parameters are user-specified and may be product- and time-specific. A plant is a facility that converts one type of product to another. RELOG assumes that each plant receives a single type of product as input and converts this input into multiple types of products. Multiple types of plants, with different inputs, outputs and performance characteristics, may be specified. In the NiMH battery recycling study case, for example, one type of plant could be a disassembly plant , which converts batteries into cathode and anode . Another type of plant could be anode recycling plant , which converts anode into rare-earth elements and scrap metals . To process each tonne of input material, plants incur a variable operating cost ( $/tonne ), spend some amount of energy ( GJ/tonne ), and produce multiple types of emissions ( tonne/tonne ). Plants also incur a fixed operating cost ( $ ) regardless of the amount of material they process. All these parameters are user-specified and may be region- and time-specific. Plants can be built at user-specified potential locations. Opening a plant incurs a one-time opening cost ( $ ) which may be region- and time-specific. Plants also have a limited capacity (in tonne ), which indicates the maximum amount of input material they are able to process per year. When specifying potential locations for each type of plant, it is also possible to specify the minimum and maximum capacity of the plants that can be built at that particular location. Different plants sizes may have different opening costs and fixed operating costs. After a plant is built, it can be further expanded in the following years, up to its maximum capacity. All products that are initially available must be sent to a plant for processing. All products that are generated by a plant can either be sent to another plant for further processing, or disposed of locally for either a profit or a loss ( $/tonne ). To model environmental regulations, it is also possible to specify the maximum amount of each product that can be disposed of at each location. All user parameters specified above must be provided to RELOG as a JSON file, which is fully described in the data format page . 3. Running the optimization After creating a JSON file describing the reverse manufacturing process and the input data, the following example illustrates how to use the package to find the optimal set of decisions: # Import package using RELOG # Solve optimization problem solution = RELOG.solve(\"/home/user/instance.json\") # Write full solution in JSON format RELOG.write(solution, \"solution.json\") # Write simplified reports in CSV format RELOG.write_plants_report(solution, \"plants.csv\") RELOG.write_transportation_report(solution, \"transportation.csv\") For a complete description of the file formats above, and for a complete list of available reports, see the data format page . 4. Advanced options 4.1 Changing the solver By default, RELOG internally uses Cbc , an open-source and freely-available Mixed-Integer Linear Programming solver developed by the COIN-OR Project . For larger-scale test cases, a commercial solver such as Gurobi, CPLEX or XPRESS is recommended. The following snippet shows how to switch from Cbc to Gurobi, for example: using RELOG, Gurobi, JuMP gurobi = optimizer_with_attributes(Gurobi.Optimizer, \"TimeLimit\" => 3600, \"MIPGap\" => 0.001) RELOG.solve(\"instance.json\", output=\"solution.json\", optimizer=gurobi)","title":"Usage"},{"location":"usage/#usage","text":"","title":"Usage"},{"location":"usage/#1-installation","text":"To use RELOG, the first step is to install the Julia programming language on your machine. Note that RELOG was developed and tested with Julia 1.5 and may not be compatible with newer versions. After Julia is installed, launch the Julia console, type ] to switch to package manger mode, then run: (@v1.5) pkg> add https://github.com/ANL-CEEESA/RELOG.git After the package and all its dependencies have been installed, please run the RELOG test suite, as shown below, to make sure that the package has been correctly installed: (@v1.5) pkg> test RELOG To update the package to a newer version, type ] to enter the package manager mode, then run: (@v1.5) pkg> update RELOG","title":"1. Installation"},{"location":"usage/#2-modeling-the-problem","text":"The two main model components in RELOG are products and plants . A product is any material that needs to be recycled, any intermediary product produced during the recycling process, or any product recovered at the end of the process. For example, in a NiMH battery recycling study case, products could include (i) the original batteries to be recycled; (ii) the cathode and anode parts of the battery; (iii) rare-earth elements and (iv) scrap metals. The model assumes that some products are initially available at user-specified locations (described by their latitude, longitude and the amount available), while other products only become available during the recycling process. Transporting products from one location to another incurs a transportation cost ( $/km/tonne ), spends some amount of energy ( J/km/tonne ) and may generate multiple types of emissions ( tonne/tonne ). All these parameters are user-specified and may be product- and time-specific. A plant is a facility that converts one type of product to another. RELOG assumes that each plant receives a single type of product as input and converts this input into multiple types of products. Multiple types of plants, with different inputs, outputs and performance characteristics, may be specified. In the NiMH battery recycling study case, for example, one type of plant could be a disassembly plant , which converts batteries into cathode and anode . Another type of plant could be anode recycling plant , which converts anode into rare-earth elements and scrap metals . To process each tonne of input material, plants incur a variable operating cost ( $/tonne ), spend some amount of energy ( GJ/tonne ), and produce multiple types of emissions ( tonne/tonne ). Plants also incur a fixed operating cost ( $ ) regardless of the amount of material they process. All these parameters are user-specified and may be region- and time-specific. Plants can be built at user-specified potential locations. Opening a plant incurs a one-time opening cost ( $ ) which may be region- and time-specific. Plants also have a limited capacity (in tonne ), which indicates the maximum amount of input material they are able to process per year. When specifying potential locations for each type of plant, it is also possible to specify the minimum and maximum capacity of the plants that can be built at that particular location. Different plants sizes may have different opening costs and fixed operating costs. After a plant is built, it can be further expanded in the following years, up to its maximum capacity. All products that are initially available must be sent to a plant for processing. All products that are generated by a plant can either be sent to another plant for further processing, or disposed of locally for either a profit or a loss ( $/tonne ). To model environmental regulations, it is also possible to specify the maximum amount of each product that can be disposed of at each location. All user parameters specified above must be provided to RELOG as a JSON file, which is fully described in the data format page .","title":"2. Modeling the problem"},{"location":"usage/#3-running-the-optimization","text":"After creating a JSON file describing the reverse manufacturing process and the input data, the following example illustrates how to use the package to find the optimal set of decisions: # Import package using RELOG # Solve optimization problem solution = RELOG.solve(\"/home/user/instance.json\") # Write full solution in JSON format RELOG.write(solution, \"solution.json\") # Write simplified reports in CSV format RELOG.write_plants_report(solution, \"plants.csv\") RELOG.write_transportation_report(solution, \"transportation.csv\") For a complete description of the file formats above, and for a complete list of available reports, see the data format page .","title":"3. Running the optimization"},{"location":"usage/#4-advanced-options","text":"","title":"4. Advanced options"},{"location":"usage/#41-changing-the-solver","text":"By default, RELOG internally uses Cbc , an open-source and freely-available Mixed-Integer Linear Programming solver developed by the COIN-OR Project . For larger-scale test cases, a commercial solver such as Gurobi, CPLEX or XPRESS is recommended. The following snippet shows how to switch from Cbc to Gurobi, for example: using RELOG, Gurobi, JuMP gurobi = optimizer_with_attributes(Gurobi.Optimizer, \"TimeLimit\" => 3600, \"MIPGap\" => 0.001) RELOG.solve(\"instance.json\", output=\"solution.json\", optimizer=gurobi)","title":"4.1 Changing the solver"}]}
\ No newline at end of file
diff --git a/0.4/sitemap.xml b/0.4/sitemap.xml
index 46f1201..93e033d 100644
--- a/0.4/sitemap.xml
+++ b/0.4/sitemap.xml
@@ -1,23 +1,23 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"><url>
      <loc>None</loc>
-     <lastmod>2020-09-18</lastmod>
+     <lastmod>2020-09-21</lastmod>
      <changefreq>daily</changefreq>
     </url><url>
      <loc>None</loc>
-     <lastmod>2020-09-18</lastmod>
+     <lastmod>2020-09-21</lastmod>
      <changefreq>daily</changefreq>
     </url><url>
      <loc>None</loc>
-     <lastmod>2020-09-18</lastmod>
+     <lastmod>2020-09-21</lastmod>
      <changefreq>daily</changefreq>
     </url><url>
      <loc>None</loc>
-     <lastmod>2020-09-18</lastmod>
+     <lastmod>2020-09-21</lastmod>
      <changefreq>daily</changefreq>
     </url><url>
      <loc>None</loc>
-     <lastmod>2020-09-18</lastmod>
+     <lastmod>2020-09-21</lastmod>
      <changefreq>daily</changefreq>
     </url>
 </urlset>
\ No newline at end of file
diff --git a/0.4/sitemap.xml.gz b/0.4/sitemap.xml.gz
index efde09f742b6a82ff975e7438cd1795028d49b8c..e9108c148967f42eb9a7fc2242690076dd50d633 100644
GIT binary patch
literal 197
zcmV;$06PC4iwFp~*Jxh?|8r?{Wo=<_E_iKh0PT`74#F@DMfaW}%HBBb1Sm~6MkY8w
zl!i7^o0K?ExIIZ#B(8vj7u(PO>n|4Va~jFR1hn2Yv|^kR<FxOr>l=DGAIlwWWg+fi
zL=#C8J8b9><9q;EmW82>W>PaUA9_GNqy=Gvz}cS4?3D${B}T91$vYz;Pami-PQH^h
zuX)M$WnHE7#x{u_l<Unkn49dB9bW>z$f^;LWByscl~t@QeU^L!b0L`@i2?usXgycv

literal 197
zcmV;$06PC4iwFo+;$&X}|8r?{Wo=<_E_iKh0PT`N4#FT1MfW`gVPBwKwT9B2OILaT
zLa`;GP#Ls(d!ea`S1@rlGxO&E{LS$GIa~D50gQJYt_Z_OJLL!C#tvW3$Fjk_DEK{C
z&=DoEgAPwIE(c22btPb;p5+3>hmnGs(gJjcl#v#T>=gyd#jRK3<ela;Pah~D&VCRz
zt69m~vTD+KXS+mA(vA8W^i2%X*cYc?WYch(WByscl~rsleU^9w>#V-Si2?us^vqpJ