From 921b9497b2d226a2a390e9de6498ef503ddeb230 Mon Sep 17 00:00:00 2001 From: Antoine Brunet Date: Wed, 15 May 2024 20:56:42 +0200 Subject: [PATCH] Documentation update: changed from static HTML to sphinx documentation --- .github/workflows/doc.yml | 30 + docs/.gitignore | 1 + docs/Makefile | 20 + docs/frames/LOGO-COSPAR (new version).gif | Bin 3564 -> 0 bytes docs/frames/Lm_conventions.png | Bin 40142 -> 0 bytes docs/frames/Lstar_conventions.png | Bin 45384 -> 0 bytes docs/frames/Thumbs.db | Bin 11264 -> 0 bytes docs/frames/category-menus.html | 490 -- docs/frames/closed.gif | Bin 827 -> 0 bytes docs/frames/favicon.ico | Bin 318 -> 0 bytes docs/frames/fortran.html | 70 - docs/frames/frames.html | 5615 ----------------- docs/frames/header.html | 30 - docs/frames/how2build.html | 134 - docs/frames/idl.html | 82 - docs/frames/introduction.html | 148 - docs/frames/lgplv3-147x51.png | Bin 4224 -> 0 bytes docs/frames/matlab.html | 190 - docs/frames/opened.gif | Bin 826 -> 0 bytes docs/frames/python.html | 72 - docs/index.html | 32 - docs/source/_ext/routine.py | 156 + docs/source/_static/css/irbem.css | 46 + docs/{frames => source/api}/Lstar.jpg | Bin docs/source/api/api.rst | 15 + docs/source/api/atmospheric_models.rst | 198 + .../api/coordinates_transformations.rst | 351 ++ docs/source/api/date_and_time.rst | 76 + docs/source/api/general_information.rst | 272 + docs/source/api/library_infos.rst | 49 + docs/source/api/magnetic_coordinates.rst | 537 ++ docs/source/api/orbit_propagation.rst | 205 + docs/source/api/radiation_models.rst | 428 ++ docs/source/conf.py | 73 + docs/source/fortran.rst | 12 + docs/source/idl.rst | 29 + docs/source/index.rst | 62 + docs/source/irbem-routines.rst | 3 + docs/source/matlab.rst | 110 + docs/source/python.rst | 29 + docs/source/user-manual.rst | 20 + 41 files changed, 2722 insertions(+), 6863 deletions(-) create mode 100644 .github/workflows/doc.yml create mode 100644 docs/.gitignore create mode 100644 docs/Makefile delete mode 100755 docs/frames/LOGO-COSPAR (new version).gif delete mode 100755 docs/frames/Lm_conventions.png delete mode 100755 docs/frames/Lstar_conventions.png delete mode 100755 docs/frames/Thumbs.db delete mode 100755 docs/frames/category-menus.html delete mode 100755 docs/frames/closed.gif delete mode 100755 docs/frames/favicon.ico delete mode 100755 docs/frames/fortran.html delete mode 100755 docs/frames/frames.html delete mode 100755 docs/frames/header.html delete mode 100755 docs/frames/how2build.html delete mode 100755 docs/frames/idl.html delete mode 100755 docs/frames/introduction.html delete mode 100755 docs/frames/lgplv3-147x51.png delete mode 100755 docs/frames/matlab.html delete mode 100755 docs/frames/opened.gif delete mode 100644 docs/frames/python.html delete mode 100755 docs/index.html create mode 100644 docs/source/_ext/routine.py create mode 100644 docs/source/_static/css/irbem.css rename docs/{frames => source/api}/Lstar.jpg (100%) create mode 100644 docs/source/api/api.rst create mode 100644 docs/source/api/atmospheric_models.rst create mode 100644 docs/source/api/coordinates_transformations.rst create mode 100644 docs/source/api/date_and_time.rst create mode 100644 docs/source/api/general_information.rst create mode 100644 docs/source/api/library_infos.rst create mode 100644 docs/source/api/magnetic_coordinates.rst create mode 100644 docs/source/api/orbit_propagation.rst create mode 100644 docs/source/api/radiation_models.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/fortran.rst create mode 100644 docs/source/idl.rst create mode 100644 docs/source/index.rst create mode 100644 docs/source/irbem-routines.rst create mode 100644 docs/source/matlab.rst create mode 100644 docs/source/python.rst create mode 100644 docs/source/user-manual.rst diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml new file mode 100644 index 00000000..4b31f471 --- /dev/null +++ b/.github/workflows/doc.yml @@ -0,0 +1,30 @@ +name: documentation + +on: [push, pull_request, workflow_dispatch] + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v3 + - name: Install dependencies + run: | + pip install sphinx pydata-sphinx-theme + - name: Build sphinx documentation + run: | + sphinx-build docs/source _build + - uses: actions/upload-pages-artifact@v3 + with: + path: _build + deploy: + needs: build + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - uses: actions/deploy-pages@v4 diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..378eac25 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +build diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d0c3cbf1 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/frames/LOGO-COSPAR (new version).gif b/docs/frames/LOGO-COSPAR (new version).gif deleted file mode 100755 index 5ba6950d3ed83f95115b0a979c1e79e4a8987b81..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 3564 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 diff --git a/docs/frames/Lm_conventions.png b/docs/frames/Lm_conventions.png deleted file mode 100755 index d1f6a30944407a3b86514cc98e88c9e9b552f20b..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 40142 zcmeEu^klx~z}G^0~;j1(Bc zh;irVd++_}{t5T&aUOf0c%1Woz2C3b>;0j& z?-3KuEC)h$2!A&{v=v|9lKmOjO*kO=pk(NARNc@(CMUUn7gF8s(WPSt7egb9xwwW8mwExqh z`zcHGU+X;)wcY=ma=Jl8_FwBG+55bk|Fyo~{QnR8|6_LJ#{XxH8#n%6;`Dr-6uZCJ z>^qt#r{K5Wh(4RO%@yY5qZPD?J!zHYw)*q?m!!*rSkO79C=N+M1NhvVz%){z5C<^J zmF2VA8qL?oJz`d%PGu5tqSnaZ|8?%DZMMmE9K2mp6k9JoI`Acsc>`r>y?cU zQ^wim_=fk!GdS)@);5!hEADa2R}v-K`$FrT6rT@knWqW(VYfb-+;!i-eFXeq-t%Xr zGY+XL?pjII2q$u5h*XHDw|As*Z`tMU+^=Pxmdo2eSmIqvkimb{x%vDa2?tRtcz|lB zXQIW|gBd)Sk?65GXm4VcBIWNjoGo7Mh9ji`Q1cboqu|+WYP7uXzUOJ-6yj(F9=Sz5 zW{sWh-3QQ$IN9+OSobF>Z0t-`IHtB={hg0P8X(LTIn8Sw^a_ria_W9ZPFI@F`(%~r zmDvQM<0ba*^#N2;Il-yz$HNkF$Y;DJGn~uclqn02e2>;wAeix4pvHrzoLv?c7Ci%f zsa(&BG;)`G@P<{^E9HjOwCU+5>3jSfTszzsihq+~&UMwXJ#lo#1Fy8dMQY)Q$!Ong zsHXEe>zWNSaPXm%lzqjo3tLPm;Pb|1`aC-lPr3AkIL!-Ho*EA{?A6VeAGxb#rKDec zA?!&QkrXb2;dAv?zmr(xGd{D0DZmkWWQ0KfhRskWO=`M-?ZgB4PA-QI+i)UtM8&Z# za^Ms+FhKNi!uiI>-!H$BVha+ak*AB^xo$WS=eZBL(t%EV1@aN(JsSs&XvY0%M6T9s zaq+84^Y*rrhwnRZ$LIEqs5}gRwr51bLpr0Ra1`zs8H*y_v zm+|*qrhw6gmhyI|2$Cvu>+8Ots?ZD;d#KRL_GFn!wT)U3rZ7Dgd3`)0W6~Dji{C0p zh(!+IIM5~82(~^PAG(+@)_n-)s#sRlH0soAOi^w*I3x3ixX0$Z>7#u42*TZgO8biL z=75bIM0*_wyV4mEhipIWp_}UL348D?7O5IjD># zmGxcU8(;q1rdKL`~xDbZ%duP1B#KSq`)hkGr8DTtqwkK#*Jtn+*w zO=_-8aGNI&la${?amzx)dJxMgtIp;y%uyk7}$%5f1&wk8R`PL+5(y1-PRP!YQ2Xtg%vgk z5^e|mXxi*W<9d94vQq)RygVKuaO=gs#6U(yo%=v%SO%AUp^%)Bes>GuwxQydnuR*M zv5qNUPM*;t)WylpG(oLBs9{K6DpY+o@Fwf!jw|7f7jOS2EK=FoZ-_XDP$jchEWmk2 z+10bZzh;%b{3Bm*Ml5N%bUCVQ^>8rc|S8SnjUEnoYPH2#{tKBa;qZ6>AG_t6ug z+6Oao$aw*bb{#?4{bR-Vc@}w;cZlZ%`A2g?Le%N0x8xNzEC_bhuUn)-q>!&aW&Mf& zyBbAA6xdfRNiejYzf+ndHnLpXg?xSt^xU={7`&YoLM6|tAgiqledt7NvxGuLTfJ295 z5$}F<02PCA8_(AE7TW@wJ$W+zir!No;t|+L;^>6X{Iba_T-&}nU3T4(Og&1n?|DM7 z3_m67I_Gu2$<)tN@4B2Rnb}a_fYGTvB;rX8T~`oZ*`2M{=ewLX^B?jF{C1o|?We>1 z;T&sUhHld}VVe;i9rrDj4Y}3gzM)cZH2z2hAWJXlGwPF7Sg6j)BS6mDijou> z%oayYi3~^sq%`dC>R~O3_VP$fisP>u zqJ6?*XJ_gNhuQDZ+BH)2Un%XY!ux>A%;A!G8P8$T8!vuNd>i0hDvvWeV zX%}8uv|J^{-(Ew79n-XYn~9BLLqDe|WrUGvKZ-sS8hZai$xve1uq~i5m23mijt6jF zl^V7fU1K*nzoA9cXFBo#Jv>mp*F@8 z8_R}X#L6Kp`*&GQ@=fkYd;j6~QUJJLU!A%oF#elyx)1BoKLboEjW zZMCE8Ogk80PYL^|YymG{1`ReEYBxCxGeCgbYJNXI{xoUyAXQ%s&uiY-;s;FvM3ik@ z>(RIR39moo+Pk>)XsfW(%Hi^bTcx{gT1fi|{n>dbFo_;sX*lz3ua-B>6k4fN%Ubed zuxihhVLJ7XNl6pKUu$9fdp%jF$1FY7c+Tan+CTbkcn>aDOiV9P#7qj;zq`J^x_>gO zz0|bDmTUH5#xtFKyru_ zzdGPV;P=XBy%*Y>(P9X^@}lj_shJBG%j1@sD1+^6)dAux~x@u(`s+V_N)<-x@SV=1%%Dbdx!F zZ}c)A(5UDM-*_RXM6;DBrRY8rXhFZ9?b0N~?LZw&c@lRL49|l4C{H}zXPV9JEa+?; z*!_Ud*AYX{C+BuH^RCnnNO#;F2tUTVuLM+m5cA0VAgwRNa4@15i_mguQ^B2yrRw(?w~PS}%FDuQjeSaE0k7J2jAMnq zxb0R;yR6HShW9JI^($6E!|5eFh&5H^-8B<;T57!(L#4Le(*&;R`6lVNs!g9g{u130 zZ#mY+f8CXr+*kE%MQs0E0aLj9bPi=7Cb&x?G{h1Dgcq8oI+-n(o~^!`%Qs{4ILmm3 zy-s9o^FRrhb4WNpjPTYzg{m52ce12aHh;7WMbw`qc0Q{;49q#YqQguC?mLnP<1n93 zqcX>X($YGSB^Q{qYSxc(c}wJ~0>mX5TrxcM_p zou0l}kZ2StS08a&cFM=a@akuy7aYAR5fyX5x_|WOFt;$$ct{_S6*O#)D!AmR-4MZY zIV7;&VInXWPDh_GIm4*fW9F<;3c}p<=`cEPm&2^f>-j zwt;E=>_jaH-2wHYvYj)|z&v(qlixm<$zMu%zT>B%`-q%ja0nvgzi{w|<1O3KVls5H zsrX`$taAfep0JRP=k9}uES&lR+k>C;p$^LlQVB<-a&qly0kd;4x;;Jv=vHWY_2S^> z#XpH;7Zljjxw!I^yf8I0hwOG9TeR)To2gA1tLoq6tO99(Zj0ZA?D_r2P$HH_}*S>}P!m(C`IajxX7izkPsWfMeG zUV+Yfdc=pDzxrL6o3J`YS#M$F~4WjIQKMEIZ@^yyRO-7xv88`|aZucPHJz)?FXwCDm+VE{n#Zz5L3LiLRn-R zExvdF+phzX@$!PM%%DnIKqGDaSbx1MKiK&&ws)1!zjNpYYkHK&5_?aq!TcQa;e|qR zUu*u0lzPDu;{k9m{=KG*_>O>HQ5++X*5%H}=gc*v*yrH9m{K}*?}#SfQH>~SJKx{| z1`xBk1??$4>M$V6;J1TAO?1P2Q5WWVc%YzKdPoQJG$<}-Wjb>jExZ?r(6qp(`2Bf{ zBn>5D#Sy8QfPW+G@_>rDdT6_+LC%tgjC3cfH;G2 z(U1#LWr7mT zwAp|f*&isVrC&V^_hqd`A7Hd9UJIXH)OE$oQ3hY#bNfYp!2h(RW5Rgf^j*n$kYf1i!p(>^ER)0o|{U))PL6zu?U?D zEFwLphPM_%{aQz`?QvAc^LL%^0Hi zKg-BUN0`zVx=)GMW;qz4r`;Wf?x-LvO7V0$8!(VgxR_<=WMiu_&8F%s6gY%3KPVcW z?A%^KoFmRpj5RprjdL)|^ye*U=GG!p6VqK$Eug#6O~A#*`tJ<72M3KX`)Oy8uqa@$ zEdq1lKOy{#DmbD=MpfWSYsz!4?}Tl7>4g8-k+0+l%^Mp=6&%l4RKNIQ5h=v=Kk`Ne zM^AA-Qv0shs4R{*x3YPyt!V!OP?W9$S4J@<`+OkPgN^c5_y@ex1y60CNQ8#X(BLza z^~!Nd9CJC=#|{?0D%zh8C>!aBbk(-;Y+J7yhQ?SJp0#tYEWDTp4d;3w#$ASU1DVj3 ze~C~BdKq|qo4mP7thjupwDA zyljvWRN1TRBC3N41eMVO$kIK|)ePWtr}pEo;EFbwo!{>sfooDZ+G!b2Gh-nEr%?0> zz|xx(GAv3P{y?R>V#1l=>)lg$pO?JK_KMij5ezn~;_TEmtFL6>EE6Pu73N&oFHE(8 zp6lN9a6V5(Yp3g?Fb}JyOAbubS0mck@Hoa*g#8zwd7U8|w6_q`IJIC&-_}Tr+H6iq zky{$owf*r>@VrY1p1W^t1RrjcND+5AVn%({2cg}!sMefI7gU)u7|&Gd&-W{T>Ux%$ zIc;)*7|{Gz#hdk|G^ndmP?{=e(WWPNR>3G)R6l_R{s{In6s}}c8jN^YFFcQX_<)G) zmuzRnjfd7hW!X34_%m1GvrUuQrk_iG>kWL@4frh{w8aHZ>6uu6fu&u}d(A&qQd5f~ z+8&@7Gq}{;`*k@=zj`sXeOx$vbM@#!it^rJ1#hMn##%g(SD9TD^ZnFS9Ug)dTW&Q; z=fI1iMh&1gSSzD(&P`lB)&(woAP|Vl^ZWV08{Bht`9iNv6eW7vh~#ZbFWEJN51Ti; zPezxxG@8&sP&<6%7GGG^&ud>)=2pTsjVhB9n8370nJ&M=6T|;yGURTNLim+Hp*89n zG=tdPH*jaqlXJu_Ja$Ztaj6=R%k|}4d$q7`kh)#RIVfjI+YiP*MqOyz$O0Q@k|`d< z#JvU~WJZK6ZlNa78GjdkK^k76vO+VYw>E$W#@yg-e#Ksf0dI+6Tffb>a5-1b4+Gs;R^>%Muhr+-Q{AttlaBojo{&ov>z*=Yh|+2FqEB$HIuu z3-;&UG~3R9=!rzSn=w|dRVJ#FeIg`rZjMW&3a;0Y`w7p5*L8qA!d zw&?4XFX8L;Y}FO`Xc_c?88$w6bd$5cT~li3dIKUllHVq2z%YHcRC);80BED&O(pec z@~PGXNl8x<`vxn+{o6f;R9^F{qb<(!@1VxhK*vDAAw9U)nJRL@OOL`b70MPD@A%oA zsV@abk4pS>eqzdXa)~^6@7LZwHBa7pOpS`}ag!K=$(>y)x8SLT{x)H!iq9!Y4~R*e}9y%qB;1vB7Re4(=cUjn1+5!wSMp^)jfI z22%D~a=J6n(DnM(PE@-uloxD$t_I!mJelZx=LxUS zgQ~wmwfvTbdmTg7H^z^jcA9!h=)}c=Jf{UFabYD$eR%YCt4cG3UB=c{?ljue@}gdE zygf%LJRT)(nQ6_zH}C}BC>b_TLoWjfa1cn$gN zF{)Qstx_ZoJI@_A-z*o87XWKskL+|z__LKE1UAmoIZkD^uN^_Ylgm{X8B2Z(PbGpm z9-wf8$TuUCJYD0D_&YsY&*+OzypOV{Do~c0;15ZUBe1qKlah+` z-$%@wzoTIR*%cLnN)oc5-%t;50d+nS7PNG_aq(d{yr$WE313QI|-ojJ2B??ag4BQ0xxa^QN$tQ=pRoU~>%2J;LHaJVe(jL1g+u8RgG1e7u@QPpXoO=}xw!S9n^+#{y_ zs7ug(Dk&LE{fiQZ_V7jU+FswJJao%e1-lZ$v%hlFm2zY&F3m2O8l4puWlo!&n9C~= znH%)|zRWSzp;U4yp!Jdyb+PR;xHTXI=GGZnHdScYWdco)^Gp2++iBfJu1gmTZug~o zQuo%}JnvKX>3UF*!6r2z6i~IV#EJU#7_`?uw!Bw9`1kvCs+>zl&0lrrwA|ou3~Qm* z_Vpnp_TdabtRLH(F}xl(6!8 zo;C?LjnTqy9tb!izI@P+VanXXG3sr4Vq<_Jv*K!+3K#K1=htzyo-I`%fcAT+lz`4? zqru?g$Jjr%gqg@UZZ!~@JUGzY5jbaMAZpEP1#HDZ22TDMywCnOFE@TauOWp{fb%3C z)2Zcu(V4;><38Ghl5?hLsHm1Zu~rWj`*$$)KA=T*+=&Y-v~FUB)FI1O=3A^KaFtm% z{&dW_WD3MCHqHb_dqUE+9Sij@9|*5rYXvgOqM%1+mb5~lnD2nm+Nm8xjbR@a?F_n5 z;V*3dx_nU>@A5S0w<;VZJ}JL=3!Z6=weuez=Pp^95*lT=w4P{dkJ)(`*IEdfieBdI zCQbNKsUHZbI9m$JlkOoBiUj0ID*;N{y0pu)Ky@i2sg!8T_~XD@xjAvXo>G#&NK zi#3RQ552(AX&cbOa@dZ0z5J$EUBH|9!Qof{250x~g|tc-?p+QxK+>NoN2OCtCsQ@M z1gl=?oGrd4lMUtlU=;n{p(Y+q z7kc=Fqo&Ds!=f|~*V|2i6~aO!b|l7+TG|`9TnvFp zjJ$)8mM@F}?9MDYY~ZD1CY0Mq(UBkn*Vnr*64&qs$_AvZmoQXf$(5w@64QAKrgh0d zJbvshjQIxA97FFTP~h5WFM;^cdB^nP2JwBBp(MxOPA^ZAb%y=Qp@7k=f5Abga%uPf2?j*(0<5c%y`6006Z!eQg+Q+p(u?Zf)+;n>d3QuNyqP_VYUdT%_TL-}i zRPANjz`k;?T9CF))py|2j@JbR7OyJ?5>w)tJI3GHZ&FFp4};rVLkGeSR;nP813_BJ z1LQ&39%I2E&pLs<3b>wCgd^1~@79!2zvhdI9!pu)oo)%_S(;d1%08U4XwWIK;9QDE zySal2#FNH>+M$ZL3}S*|R!7ExDX))sPJK4%kWSNsEC_iRuxTM(;<8ToRqw`?}4Eroec6Zz+SsxS@L_>({RiH=9!=m|lJaG&|%n@)ZyM05n%i2=cg69iO!bWpg-x22u?`Y0FW^ z0Y!*1%6!sqFDtsz1-DKabGjjDjqR19Cpr<0hcZmoGD8sVc3!?0&$CL|>HSuM;>C(Y ziMRDV%#E_vl0Du(x2H+>j3&)D4|?7=@3@M1v(0|$r=lxQvvu>ouy#H;ubGQzahAW5 zTh}OeFT+uQ_i<=*MG_a{PqXF1I{Jb%z&!a;OXxPSGdX5v=W%;7Xux$`=aQwh5DP!? z*38#hKzHAw=Os#dLj^vs7C~8pH50h1fvxR;giwfnbZT5ioxV=0G0F5Uv4+;Br{`tN z`S-i1v~3_n0nW7oJUD9c5*Vp=Lza7A=%Q89lvkq#O|`>MSm7j;8PeN@R>f8nX#C(C zIM`dTLTjh?(uKiz&%{d<{HI7Jf9i^)70+}!!85=oIW*xNUg{&!cqHjxItWhs5vDCuQ#roC7Aem(&&|(ia>h$Lp^kSyeHya9>qbRR zZTlsYkb8_1@Oc!UrbzSA>aEoYkOwsh0foW=!p224iT1l?@l+GoOMTpC08Hf=Gu|ar zdez(*4|E=9aq()M)GGZcqitKLUXQOV*8E~1!oD9ga%EDpC}g(8O^I+)3uuOX$2omA zGap;4&QMPqwb9e=6TS{9xnz|3-j{BgF$^{!hR~wQ$dCOv>s=<}J~;B2eI5L8Qc
A=BfSYl3w;}AVF~)>Ms}KmkO#qy2u;f*IQw9chh*9Q)_EFRDoTpm`6pV za)b;l*=PqMx!9)B}*G2XE+7;%(F+RZ1M<#XUDopSXUVHm0_Ri#vib_3K zsxD_?s%RNr(m>s`?VT7?xop69?!(a}4R@dZ_LRS3c>J#w)vON<<;RJ)K+Q;xvs8Za z1Pd0_wr9NVyqh}Bq=T^uX1eQP+H9}xMKDm1q*+g0X0aqFsX;Ugeb^GdR!z%)p!LKBqLa4%Yh<#!XHs5i!ApIKaNKJo{s zporhO@>dua-=^gQE{`!8LANn=orW!WKKC)iw%b^AOygGOstK0GZA{v#!459dXxAfU zk`n(4HsM$J;F(mZbZ{%tvx=I?7?=LeZalK98xQJ*QlPDYCYcybLvRK|FhZj0O~83E zqx!j@P1zc=X@8#LnMdxou!eCFc)G$XN~nI(*+p53Nb6C%Q(0~6N|T5A`2gr`!d8tN zAaK;Um*~18_Av1^^2v2RS^2k=tlaN_O2#0KerP z7lAaYrO<9H5XjZXg~?#NdY9$Wzi=38q>$wbZEH?1>0yKScS1;OQ=(YXe|Qc{AQRA` zHA$*XlD=P}zaO@CkxJbrFyId)``^}?++JQZ#v_<#UI%(M)s3pVL2XC9rP(a!4^SG$ zBp{pCRxl&M8Qqt)^ry0b-#jz_4AcJF0kHGW-ov+kAM<6;Qu4Ei&P$^D>$vb25 zD`=jU!=rTbbOsF?0J1Ku=uF8Q1&dBjDPTho(0!Allk;Sk9}CcoQm0AZR7dAAx30S} z{3pT2-Z?2Z)t3y|eBHPhR1Tf#;Dx8#5ceq&&Q83C)bu57xdrlqPiH6&)J?wgOIvz7 zzYWoLYD#BNR(B!vSA6l-p2@)(qq>V2lja1`&&+cNseP28)VI_?=RoJ9dOhoNzOtY` zLxX8g$pDf`esQLkukhbM?? zjP(%LV&4=u&+z1i-yHIuXP-SLWD*0G1C!hZC#v9N6W0SR(%Y4azmwlt2^9OQ?&zDL z2^Rfo9Va)TTpQKX+{9 z5PZr#Zz7ncIAyXu+M{`(t~tnSu&UmM>8EU`Y*CNClYr)98Hr0hcuua}nn~aT9jJ`S zM%M?`Ua6vxG?V`1RDmneq9Ca$$c|K4(d@(<-TXl<<0Xhf;U%&0 zVBI7VW>7ELoG|>V;^)dV)P}P&NV*vi!nbn`mSTZ?U91OD1m+tfz;orGbqY1p<=|Bw z=gdw-v9m5QAr+Ca!wRDY=k!jTwl`~J?a#cR7k!2QLKF2iP3sO!-h3dyI~{fLRzc{= z+JOn5`G|+DPq?I}m|&6^>&0rY!}8z2^pXT1V>+OF&m?2?J+HcQ5yEcIG+ zY9jR80x1d{q_tGAX0E(v<58e`>YH4?Cxl(wMf5 zu5iKHZ8E2&E!G^+m)`s696_vI#F$I?JAAtNBbGPJoZR?9dj3%YZ^HV}UStjd3bR=w zgn;$G$|R)T>->91_|!pQ_KQVfIO((}8>xLd!8#yB-XfB@Lj}v%!+J>pkl|$Ky z3Y6-|lwYJ@l&?u_Um+v}Q-OKu%sobf4WDDWyxYX?}PPv!SUfC^7{KE&Ha z%dE?>(dfQaxRau9hxSvpeH~Sp7Wg9k+9d6>#J;kj)-Fzg)iRG&q4}hv;c(cU)H;}b zLQ8W>@oz|fam2r=^XJbY8R}d=?wS(#K^_xAy7Ilcl28p#Osmq;tuwe*rh$RDjsH+L zf*33ol3Gd|^xU_%uc(VEIU+wXWWItmGGvs#Dpm{;n`zds2 z2&cSb8a`rgQ?GC9w@wM)Zg1>R>H58NojUya1<%A}9fx2rzs=M`TXl?T>25UK?+=ab z6uAZ(>K{|N?uY+T;u5D`e8*^sQl9h0)1-agPmjsXqYxYBY3u?kon}$?^n~}Hg#*p`YhcGh@@(x_<}Ckwan1x)LXX)zt%JC?b_`BvHrT(V|C$B`skXJh>VB~ zr#SqFl*IY$@6s8n`A0#m@3|GoRk{Q<-S5p(zRGa2lpPN=g$=5PZ!Bqco&?%UNvDhN zA9||~r3p^z_FUdo^!aSP*$0t}@L0#Cmkj12BTsG5tGG~T3VUV0#u>NiF=^dMIDCFz zoF4OKmnhK#1~ykN>Y0T-9-iIJW|_>b*;cg!?RrK=*O~zWCkbZfBUu$ym zk4AYW9kT|_>I8vNmjgLdvyf(xw8pLk{|NsmN3X260dbSyj|vje?ez-!RmZocvr67a zYd)m&W0y@HUq1^rWX;7*LfPWgeU^r&<{h%2jKKroPpnT?<3d28OYi+0?xV&x`@M6{ ztPDjhE4;t0S*-8jo9<*wQTz9sJPt}Nxw-{sU!F2l%DynPoGvQEIU%JKy&ZG4p|VtRw=={$%*gSX=J2l^Px0**ys-u>B2&1f2#I2;uq zj%hSSWYq|%`t*&x^b2Hy(Nr(|<^YWVfyxTngId&!Og4}2heh4{6hU+E{(3Dh`cg9V zy#IeZ^$-8YQ*TWTaVc>TE20PP%RO_Gr%-vzYMGPW!}l`ebR)Q*_65V?<8zGA%qj#1 z*HU;o7+`4o`^&p^I*bYUTXg}%q=mL}E!hg48ZRZ&KkmhXH zxqm|*e&c5&W71ZVJ>-7bX;%ueQI+U9Fe*>cT{t z`2JO`DG+#vkx+}qay(OIx6mhF6~4Pr-9wgmilz$hR2>TCUMyGlH&%vO+}+thR*|DLVJ* zS6fzjPhbfr0P@sPj(ZY;702=iJe|6Mf;xpTqk+ucL1rF~TdbkpruN7)A|fvpXN^^tY)FwTZ}y_YRP!+#Henk zK#`Cc9G|De*!eEKQ!Szi0B6kM&CV@u20qD~D1Gv!hy3FNDXGwHTy<5o$5NDi3MtL_ z4=p3hXUjv_xi1aGx}bF`aOCpA2JMmw(1<*@Ll@@_t2c_>+SzVqHXCD`5my$Av1U&^ zy=Wa0+6BX(DU?hnPc9cR@R%H9FW8TEVremzy@R1@qE>DDN8*G8k)JFSonx?5PI|Cj zRFgwjgy!M6-#wwBJK%F@FZF#ugDgYZmt`fbZiLZV#b3?)p_-HVO9k40nLHLkIq<{v zvaa7M()O4JZ|Q2Z$B5KtCCjXc7GzCbn@C17%hOyyzX4!7#FXV*M{8$p*PY-|6d2I` zPJ^b@IOqY>IC1?NJy>_L>2h4QmkBLavFutCUGn$ZGShpW?s)ba`5f6yENQy%iUJpMcMq-j|r_qYOrnb!09Q!8eOqR z6!Vh@|MisUe|q}USx@2bJ}YpbJMk+??;i33z&|i@0&%QD(W|O76ngKRy@xK((gSNc zXzuQoYl1aXF4}F3mR|Fr5lKze`5DO9ik6u(elj};&px#9Rm@xU0;Lo5qal|}8$Lti zp#iASmkY?ZEYH!GFRh?1y%)11uacMJN;VZ1Rd^^!+b2-sa9DCpDZ)AL?r0nRs7qO%px8dL+$MMym-&%3bAxs7N;|p4ZXR<>nE`XQq$a~LE^v_Lva{|2pWMM3oLoOXKh&at4;o~s9DwKEg<{@4f`#*~ z2@|r3mUVNArGZz2$A0*VXWQ}7c47bJp_T9b<5H)b#bI%K(=^cIX%w4@zI6I54-lug_VIH(cw5SO=5;}>~W0ZYTuT(Gg zTz1-a9J9Y-C=k(`_9uQ24RyFgrW~6)^Q!Km1O}5>J6~PCq~37ZWwz?pDRV}8B$eP2 z2*n1NyD21A*q{9KrA>d;zHj^u&wD5`x|Bg?o|b4bPu1rMs@!`}=Xo!DFY>B2PjJ+r z(qyIDcI1eFckw15c1%|zBO|FdhI3^`B)oQi^BC9tiK1kGpO^nTjarn3&3}dq=wdkd z9fD6DJ71*}5NJCXzzzkfFl2~KSory-FgmS=wt=peENHQ5<8&ZX84v1>vns1^y2nnv z@2mHnaPl4oz4FQlqIg4iu=`481ff);zv0^i?!v0kYtZYvllk`wd3ToxjUEXO5vR#g zJxPa&SNmfHcV&+Hm=`LHMOCHz|E?3zL+`*ZnVE6Z=D{0@%!=;SHbV_^p~U)7MB6zM zu*^TIIZC^=F@)_4xZaF}O09-l+!3#DWrS+L6Pg7In|p+Oi-UL?)2!1jBH+{9vwU*C}%Jza9ebkwRXB|9SILM?Z-uJ`hkyzPO`}0NfF{ z?Ze8gTyc+Zja=y=QP-vQooU2zjXg>%7=O7yfSZ-E8Z8B{ggq0p9nM~;b2eUT_9iTv zPqL$*8w^xu*wCnH9EnR<>Yj4o*)A196EC7$6N=ymmzneHivWXzN z21_q&Nm4~kG5R<5Vbi&qxt26l+aW1t90rIogc_34s7 zU%lPfCj#h)B0f60$|!pgce)(xd-i9=59D&O5CTM_!Kl`u#cR)q+V0g^ zT+QXvH8!HGHx0F#sw%+#oy+s&^My-u2KX(-MR(S+cEe!|1Oj2UNxM&teg~EKx&Vl6 z2&+}H?X*9^ES!<@MX(&q>#@{VRS(2`qgHP7v6*d6?X%&Dn!HtV(LZ2LqI;-HD?_vPnXR}c623IRmU)4F%Zxi2hB zTLnhF>PMzM|87|P%33=ZasG39J||VFOn~t~MgKz)ekY*Z^j|3wfCuFS>v@6zbz3D! z+y?@7up(`fj80_XywZBbXElnw{9q_oMn=6SUW~Y@888ZqA_BZfdwkTbB%w&3vP<7; z1BlD%!j9jAf9k!I{73>4BFikb>KBCB((=Oy(e_KuJ9o^qZkGB3Ifxbog~)2`8*Y#a z`GV*&bcyG(uwni7gfVrMv&u_gk{KqTN5lw#t|aro6FsvkYZ4g(8f>A)UT65r3!(%X z!SH|Rnle2j;8T@zAUok21qH28-*$kQ_r3`iFHnm}N|R;_;IO6u6k5>8%!81!(N-Bk z@ep=Y$}f;Xhv!={1SN{WxVGQ1S+@7B!BVuoZ7`i34eT&L1a6p68klQ#a52)%KNN7A zqD%94rFRK)5AMg3+muzQI-S%jtX1CC>}$Gc;yH7+Nduxi#4(GwQC^^wh_XvwA?h~) z6^Z)?hry@oTPv%wm+Z03D-bYf<+`3pOX>g*rI?!Lkf5V}_C^pCp#Pvokw{9HW=qmx zZQs2(F?T}UUM64gu{E!_LEC_$yr9yvrH^ z4TaZ7cibkc5hMm8^LK*A$#fq+WM%xCIBL7EvlI5iC`-q~sEK9EDdXTas$;5&GM_qI z2M1j`7@Dvw0Z6bO%97&DMK9kSi0%A%LQmv;DoAbT&#<164Cqms))5k-H0x$@BHDuAaOmjqc#=T?V)R zGW_#8?^j1hZ<0h;2+p2-nLiBl;uS<;=t0i}0j7PG*RE}`YvhJxlzYLAWOsSxbAr*- z45(h0P+OR);iOf?M<1cygX=ns(YKRSI+k<5^awKQB z--%gt+?Mv-PSM-1s9#zoC~CvQaRLda4U*q}geL8xjmE4{&>kr?@-zT-Xkez=)a1}E zFuBmB>qzv^5N460-uxyy&Pu`03nu`NSfMVOmlo2)xo-6aHhx&jMT>{9+o8-75nFAp8NA^4nPXY@=)Enad%p-D zU1)i!tniYs9ME2$Oq*X40ON)~h6!xG>bWyzSbYz=ocY2RmwN8$@RCOVWRWs_<#Q)z{9i5N<4- zwy%pK}lErLP4yQKnzGv9$wf2?`Etchsf?MS(5k+(HbAX5;(xwbGoMq=f3^x6Fh za1g6#2ruT(9(hP`bboTa&wJ6QJ8p#YzXNYh=O|trO=L~Sn;F&41(4sfw5t)wM|oKi#`auy`peCeBE6!d=@fZ1s?bve&b_Ecu4py z>b64-7w5DDs&VuTod&-eW92g6huct*)h$cO9-2>i@5kA518#}lCg^X1?eJUQ?$kce zR0;$+g@O!uf$kKYV!ad6h5LuP3#{}NqsqmDwNT_!8&1Qd67`;xWfhWc1pdWnwDeN` zeB?oS5IaHPOTVA1bEaE(c;jERSM#HBJ|bK&(4P+#(VDTjFe2o0pOA3|e@g}u1EWjE z4+I3^zq7+15rd8+F(LDspdBNc^1l zO*`fP`sblYF<*fc;kp-?begS=Fv1fHNg;H#os|-h{?N)51@c)tvU7|&eB2+Z!bz02 z^4JKbQyS71SQK<`8!v#8xWe*1;2+b}-p>3lT(Pf5+@ygN80A=eM_h&@?Kk$Lf=PXX>OLyd!DLFOz7G(Kc!}Zac{G&$?v9=s=;W++m(G+aEwKDAZf06c< zaZz<&+&796N~kCTlF|)BH-ZAf&T~J?Q1E1A%FoaF#P_((xTc@({+{ z$B65z2$+&OK8_Q|atNQ@b!b-1`^Xq8f&DK2Iwy^JL4+0i`SrL-v-RsT4hKYgVo~VSq&!gfG)u5ON`8qs_T#6 zrQ$(I97CdM)8oVGA?*9Rg!b|qn<0aH#@D~t2WJH9?wkqL;@-OAb%KW3q=rTwf+xS@ z!Zsje!e%QpN&MY65tn$->YRC~m@Iv|OM+HW9U7(MSbz=n56oUj2wk%VcKltc4~XEh zo4wLq&%d( zHt5MVULFAZPIBGIp>h(aInCiGvXRHz$ zL%n(0f6cB)D-qLzS@6lbVk|J>clZ*{{*>b_<&E@ix4>EdvXpmz!i4Ik4S*=$Rtc+G(H(=IkNK`B+CLyRhHB8kKko zA=u_Rtn3c3?x^J&NS`iS^l8xAA+3$>$9Jiy?~?1;p|6cnw<<*aK6%T9KETn%wij!g zjWxLO!BdxK810F&!>zXs_#-3DN+C|nu~n@HaJZ^*Wq6Q14`5e&?OC27^2Fa{Ue#Nf zHDvCTkB*Ft%?y5mZj3YpN#*HQYP3Wxh`?9cSI36#U9==X8Hs8O)d<(vq0B3VT+ppy z!F`gjTGB($(UkI#0_(%QM$7b-@+>UG@3A->5K6Htcg2Wb@9Oc{Ck721MB^_`nf1V? z{xc$)K*Up-q0hsSabhCJCSKLHCW(KbLp)~2u^^X2JcjTIR)r`p30J^SX+}W*e6@4;9@x@uWuRW9qC<7!eCF(uy zi_*?}wtiXPSmi0SOK4QnPp@1snlo<&pV)}=%u77se_8z+{!9;0lTDls4@xXW!Q1BU zZ!iw~(>gHzTEv7FJE``ybawR6Qv>4?>?_Uznn~k5?OL-vccC_#eRiRzw;d9ZYmW9) z2s?mo>=_!lgR#~8Vcwy(-Jj+#0y><((qH7}MJ5?$o$wUN9Ul!F9(oDGOUJd^xQaW? zv_w3ka@LD#?y3VM62@X|uN^Cg*dz^d=d0IHl^YW*%r;;5Tc3>}$a zbNP0(d@F+S)LHm^EON6uvTO57=SAFadv;lC{n?;UqugNw=j!VA??&U^A)n)yzm4-raSAo!k|*Lne2cj$7lZQuvGLGM&Ku>O)eq1LAhBA$uIB|CQ)h-+iC z@W>Edu=wu2 zmVy2uIAoME%5lBJvrBYLO~AHXT*P(Yp;(bS9o##a`$w3ME0tunpHeZZYsY$xG;Y5> ze{Ad5epd#Bg*eR9G?!s%98CQ6Dg$CK4Cx8C-iQCj8Vvpy81bh^O?o^1p^H~#!e{xB zlI9C`>;u}c)nT(rzZALGw)PL)^&TTWZ$jJet%hTd3uDUjMQSIQnN-~GYz;QReev2Y znR?b(-vdz--u8)j9$SG@?BT9^#dj!b#YW zuG}p>;$1AG%PD8L548g|GbKZxb(Ur_rHwlUohisG%l;>?4BK$-Be_Xlc!u?)f`3l; z7}U%P&5Ty8@}f5){cP(Nl*5%nmh|UAmooHv`9soq!=juYIUO&QyW|7PgD9|%3`dA| zALt#EZ@whRi>}_Pgn9@YYaqUudC|jnCVs0uL8g14P*DKaG1c;0F=9uxcdq*J&Dm%& zv`rWwh6G%tBO4?7^oT*RLc0ruKa3P$ukOZ)`$+PBGd`7E#_s8+*>O1jfTgbQ&Bj&d zbx)~%zMBiL@>hdUwtz3cF~?y1U(6I4LE?%DzY^Orofkx<0=Du@k2e%~6Q%DIP)wIR zWnkv$%rOah{t)pMO2QA3+1)_DuzBSg>11t1(XkUeNyl8LyUXuwj-g~W9&l0No!ihSe~~5*hBsj zD_I+XzPY7KU;AY_k<~nkA>h?vV{uCyFSn_+FCCazgzh*m7A z*XTE&?Ippo|9xCMyG$l60C?!V+)oi}`~GnZ+fvJ$&qDE64#vvN8e)X4I3Xun-$S3=WDQ0FCLivZvMG!8XW|cW7$@}&%huVdn&i30ME5VH! zZ}usQGe+^0?~;-8`J~5Af9G_;4gsNokINB8It0{XJJyBeJUlekZLcJyId2LjgZ6|^ zxcvTeV0(h z+{fGRliX0e8wDQXY91O(Y|{#RSOp=gNplGxkagrmg&xqPZvDkb#*KrF303u?bO00t}w@;pux@(EB_f=y|q5f*M2h z3PUoZTeOiqe9a3RcEu2||LBuaH)9Ji8@&Lkeml18Xsg3!~KfxJDAx^H2tv_`3J@SX>uEjl-iw*O}sszOj`DH z@azkI<1ph&Dizt$yLe7jp^qM01T9pM?`Sm#y3n12&o+Lk!=rml$BBn%hmobEj0GSe zxJ49w!|iIy%P~Yte`BGy8JgWD>c)Wg0X6B7AB>pq#`Qyzz-u3i&P;R3Aq+${3I`HF zI&$v3EAtP^hx{7V2njZa(@$$Jg|UKfzsOnhq#Qec{;yU24tCv`mlu{}i*d%i7&Pfy z7EHygllrt5t$oKH>9vQgU|d&l*M>2`R;ZMhw4q?%tBvjN0?d+U=5GSi$izOH6xxd57N~<#-AY~nw``h8 z&1TDJXCFVT(9XS)%DHrFX49Z{!^|~Uupn}a(~%ymDhg;dLUHXeujXiya;cXOU+N^; zRrh$pnN}`%!vhh#j2y|ASjv5+P`+W{neDQt!9`T(6A;|}q?GsV{jl;@l=t@MuNXdu zx0(|AMZXYxS<5{t6BVaG-1guTLbPc>ErQ!WQ@lgz=wYE-*+22SCXqwgj%>}dr0 zUXfL2EQUBYV>xiq-?z|dmSIbsl<=exG z#8>>|UG@fE<7RxaBah-n1EykaWq1(JgL5EMb>-+jz^sGf!idiaKY^h>08!`^JcCFr zFOW$;Lq)}Q8M)1@@yjpg2(1#wO9v}B;)+N)j~WoD3l}~}!}sw4nz)O2j%FVdL0Ds} zinWk(a|*0$OaET2-mgbnF?y7j)Nsq_fpx4G$kROq(3iXu&}VEgp&7phtg2D3c5zQ~ zj~#$4Ps13K^lM}Zcczy`LhN&KJlz=UDp*F!fs9J&P5Vw{s;lP8RlA!T3 zcz?yDJX`@mnh9kcf6Ff}4N7@(V|v17yu@`C1sR~M{%cGO}$a=-Py7*avzx@*mSV|0ZuO-H_;zt1dndm4&KKC zT?0~vkW15Il;OfjIRm2ZXhO7Bo;6s%>qB%-dplUm^w%>FWJt<*#cvwVfD9_WeAGrk z$S1tsH*5(HH8QrvF5A-~gVW9go8_h#&yr(Ed!X@GH*tM+BD^!=@ZhGyPnifO&c)zW zJG$5=HIE8qOYH(%u0D~|9ae|}tMJ(d?S;*i|4^GcT8(x-ep8F@drXD*uW0}L`RotD z_;itp0VWaOG&(8?Q}VUM+?^-DO ziT-J2?374x0(EV5T;AbvAJvHMJAN_X@I_8XuaTVDcRHBrX*+80Im(+fz64Nuh?yo) zpH$xKONY5T&6t*itIy4aYWRm+eN=ynia&_59j5*kM7woXgobi^5{W|@@4TRwihNG{wy8mCu7txu6hrbm)6mjl*mHj#Pk^BT1bWcL*%T8LI1!Xrm?22FS(q&IVLc&%> zvb88 zjOX0FkG}|X^Y%vzG+lP*TeY&}NRUAruk)=+_uctdVf#ox^JcoBc!PX&rPIA`Rz470 z(Wtjc+`b6N@&&lx`rYYjCS=p`ZQ{k3Dkak-kFDp81;N^FNH_({sJ~ zN$bX5YU!xoJhSeRthx>E8<#-y&~C2j^C=L5{GH-;HNN03aioe?^SNe@*k<)(%0cDO zlS~Yi$Dl3Y2^l(7zuV8+=uL!1wFp-mZg%c3*u%SkqFpr*ioE!VPWA_g!&%oi0=YS> zi86Y%0*z?Uxm%!l$nE_bu)PiH7iPwzV!qRJmBKYSzS}uVF*a8f{vJ_O9Els z2k%dY0|s<$2INpLug-V&%Pq#N>RC@y8CCO5%SAy1brdvG7>;G{P>!R^dytdDDY=G4 z5sV6kT_AnVQ=HS{2Ah9!j!ygFY>QXLS>OceHT zwfgm)0w}yqFSsKq9de9&^va=3#3*;DJ$GKNh6G&A`IF@2 z0AzIUcy%zHbmc$8QC5LqRXIy;x5{Rr3PdoFp+81@gZ1GY)m4dwwvYlWVjiohKfGi} zuMTqMKzU&L={XudKmP=g=qvqHnHVOs5GguwS03}>FO4Vj_l1F2-k>|!6(c98DT-+7 zZmsuG4A9LJwqJeVb#=NTXf{OUd3iYI0(1f0=bG+zze@n_^nVAruE4{ypggrA4ZjJN z|Bl92_&8qwoeZ;@sga16V5biT36cg8HQ00%av(mCBrYog%gDd~JGq6H=Ys#A_F#6& z`Of^$EP(katALd;&-$MWc2^x2?)PF$5Ue8KkYnvG3<{30;D()g{~l1mE5cw#y{v)^ zIAuGW45S?kt>R`%P4$4MPNj+%=Bxe7;JqPS1@r<)*{gG`{RzA8y2xgfTAK4r?v+1- z^MHG%X(qEiwQ6i>DvN{lPeiP=AVr z1pFK;Ap;&r!3l0L3-ah2$P746K{J0c3Miw4?IdzVegBReoX@}rQH>0_86gBxcfpUy zH57&WhbRNM9J%bFeD~H(V$-;JX~^AyLVFgcV9lY~bsA*s9T}2p`u)Mikao3HTrcFrKff)V8CaqyU#^T+ z^AyWo$%+vKJ<0}!OG+taqu-+unQfBOIhV^NcxxWt1M^i{y))`F>OT+(5zjk}duRm; z=I<9shj;@xf9cJm7J%&|`M|^{J8U%m(~wA7<@F1uVk4?WdgzS&`#5k&+OFk=?Fs0Zy0JlWz96i^`rvVoM2(vunt|dYLK?+9Dv0-8y{fc~ zF`x|_F(pcCJiqCBS73RxB{iYJ#DomyDe_>$z&xg&ej#ih==^;~8Up$bDN3}7#xtG( z4MjDoIdQpKD%TErkjQU}y4CBBXD)O&oNG>`A3uyXk+NaXPCSW?3l>CgiO=_5{CuA= zrY9om-0>Qy38|!UpA(H=m?QQv2&kj|(nWrDL1v>wg-J*m>kSi2{lMAn$V%wEcI`f&~DKZ=@ame_aj& z<&rO7{#ojdJq6KscCh23Zt%S1mwfeVn!#;Dz}Ku1RJBb6vX>0{VU&I1=)_57@d~(3orPfz;BM8Fm`|jxO9#@pf{vT&!a!!dpg-Adn-8e0a~$u?&feSo z^O6{qWKMF<4+p#mY8tOmKICSX>lW7l5{3j)#hL{jK#+Oqrw_U&d*7o;_k&f%ykG+3 zQ>Yk!2K9u{%qjTN6;89E4?bwv&gVy4q_I4}2|tiDZ6$b>_)URN6ufv$ItEb(d8E7P zX2{+d7A?}O4Be?(z@d3AGt|Y@6~mlhl;N~J)rpQn{2QoN+W?^O^n9mrrK6)mbM_i2 zQs01x;Iskwm(up75MtnH<}1%PAtBnLl~v-$!9$KU>UYVRp|I6<*Y>wz(QnXPk>l;B zpDtFJ;beG>;cFqM)d32|sd*qQy95pZab(WFZvn0`Ci?9{2+z##${E)ni_v^D!Uaq` znm^Z9$0D95bN&UqYpp>~HA!%j+<~}$%y`U>^{?+gOT9^RvFxoJn$1=fP(^YIhJ-Us zZ;lQMOs@pizi@lzJ0%{%auE_YhKdTitc(a~2S-VU5E*5rM8b?+>aAymufTwF0qXUt zG}xH^RRCM;kK^#SuHE9c8Y@g1>6$9HQ0o>2I2@hC{R1FC&kMG_TD6XrGgUU}CO}Mi zK;My)q-L2`Tk`HL@bE4J4kDuh-~^4W4~&%=YW=&Pw;OgE&Z|^%lvFMDon}2u%Eff6 zZK>r*O)#gk)rv@;(krzp#d7e-J$@^r$^H|4ykPqGj#DLp9C@~R8 zqCvhy`sd&!3jA-Acf#x|F2>uL`3_{Fjajf!1&jxU&F3{=&NZ;b_Li_#?Z`5i~RA4mQ2b_p=jk2j< zC6z&B>gk?KApd28`APKxk>^ zYyou3&f>!p_DSS99w_mvrx8PfE2EwwnBNLya82C#Z?nu(TM4egj8#Sd;j+KH3(Qe| z4-o`f8LUKC&@V@IgycLc^|Legf2-+w7!huQqa0DWFp!4+$CQ!}C@3*YK^&yGaTN9a ze!cAzdgf36-`~<%BGVOKgvUlCHuu>lJq#V&PI<*Q6ZYZ4TJ5V}_t9|$RR#v`268Vh zbm1)>X z@~!F%8)K^a&kOs{8ze9G=;j3~9<1=cx)`FnJZpWq$b|TyV$mnCPDpwnjfN8z+^(YA z(RDDf5A{+RkeC@m_m&}qC42dq=~<}dxwtQ>&a@s(@gjq!-PrINu$2TWF>;BeEAQz2 zF*+ftWk6|D<$9f_cF!&hYsdE3^RW7yX?}_M%XO#Z=(UjW^DCaPT!t?v2}dnO!kO1R zBhu?V%4YX;<0PUsZn@kEJ00Y@p-A2Ad{T$W{T~+8B~@LaSw_TGP;CqO z@Ipd_ls9pEcV27lY^h$*^)4t!#roG3=@hAL9C6qb`?TosM0Kie#4p!qY=~H}Co#3! z=dvOC4`GGAwZS&-$8I$J1>=fV#)3n|UTuJgU)(smUNsa3{x@KgZ~8qg+Zit16>e1| z=1$FF69p;$s@I~1Xt(~5Zg5Gqbj07~H=mFq1wGF^SUX`bD%R2M&eq90tceJ4Hg=kK z!_RdncrkS(FyBOCY%^y#4RPV&K ztJ1z%2zpI}w_;C*WiQ$j#$P!f$-2L1GVa@TT9W*ue?@`LvZv$b)ah2=q_`&b;IVl@ z-&ejkG|#T)o$Ze99U7g{Kxc!3MXsKicnhb?Sb59t%a(3UJk~dpDmMNTquLH}+*}`8 znFTacBpW(7uf~7(ROsEPVHW-79Jpdj=`5eYwDe~^|DkJy#|T`bFINi{vfGYu5+2?!3Hdfd4T*&U#7wYLAU5r zRoZD(9EYRSXyj|pRCv|O8C&|QoUzG-RLZXpEM2rY?C+W zobCn_tOK1=&6>mp@kBb$pn9EgAmu(&3y_w~Kw-11@cZ63b3Td?NsjdsPq4SdHo z{0}AE9%z6_-#z12jz3auK`og$k7mmQPoy5sC(O0*G-)%Jq*=w|;cj6pBt*Tqlx-d~ z`!bu}pcRN?GiM$Y*S8!HH`8aPzaZnk@_yQB_8Ni4c6btQrb!Lrv<4b#W9Ocn577>l zA2>cg7`>=&vEo%R~tW7$?ig+KEfIAU+~Ga7*VB)fcW4a*JxIP#V<3LH7+h@< zjh=K-8-Cg4`@RyX$Q*@rRf(QkIBpXB?@ zEM-^_XC$5pZM*&lSh}eZY`vZxGrKY#^MsdQ+=hu;Rd%Tm^hOaWF0cJf^54Tl{-k6A zi0a)LE2Hu$$%Iy^=Eh;%Cbarmk7zfdTY-!oWJWi7;V7Tqh3eYx7DT!-a1S_&GvBsM z6INQY8ESmlt%&U`-lKpayZ3i7UxOO>gIdo27l~*GH)ewHHEJUhvhUw`J zWtThOREHb9nXe!RI-A4$sPIf?g9>5Yu2juDulMtTu~(U)$qqga&}or3?M0|qWwB@z z+x%2U_sfbl9z&T20+^pl@N*HZRup?0i@(Btp}`94Z$@IS-3`dGDv+w!WRpzUBQ9U4TcAAbn)Si<5eRL0tk^B}+O zYi^vZ{+c6F8rx(>%5K6hTgAD3n?pMf+pwBMX&b#m`=xw_^;3=$Ar}b@9nnm7g4{O~=btPl-0|A^X+AsUE(LZQN5nlH+ z>g#rX=$k5G2{J~5X-oLFsdG1HtUkZW%f^O>ZDsY(5!F2bD}i!7TD4v=V%TM@#*pF% z0gIdiGxintmqEz)$kM$VHK!FgvuHbNYGK<~U)RD)Iu5a3C=AgD&Nr?k_UA7cTSw%z zo~BGeC8_en9s4Q@ah@_(2YSI(-2?CKadly#CSggO-CI&PZzNz%J4#IHv#SvEvN?$` zUMI*wPeg5XNO~?Y&L?z*kNCj@>s!{JP*BdQ)YO$pL0u`yJ}zw)dP)`KZ?6@+bMf^! zY2|e|Aj5jnc;50}Jha~2aX3Dz#q4FI2W>yc&%j5W4zO?N$38s3#$pBrkvi7f5zd{! zFC{ePm4WzHEnn*QN4tD>skd@v(NaZz`YWP|7yX603yEdLZE^Xx#iz`^so!?#)nJcy=+CMwj61Q%y zLen*sr24$eOSn62g~ZR75+m6LMBaTy4- zwO9=BNUmyEm<7VUq6*1lNVAS*f2RlRG;b-nH`-UvS|`R4QPDW6k@Ptxop`Ht+u)wT zA;ymL7Tjt{oiq0Z;W6DX zRZh98YgzX;4XQb^=cm^yEL^jNP{|S0u}kEBXvu}-CSpl>zrBDS8<8w9+?%aFb&-s* z^O3wG7Jo&VFPg6~=Uk)Zcz^}rEe*x?S|ZkN{7pgDLgFf*qM4l3R-M|++l%$}1I{2O zLsx+*wOaaC;z}w08Lu1BXSPp|ge4OZzdE4{I)m3_jLioFVsH{{m@5FJ7?+4l7oVV| zNdu?XOgc;>C+I*ob3xk6_+2hXtQpkn&3Mk3fAp2(MLiZC3Ud2B+6waD;;%Xm0I0st zXAj3d-3+YRNu=+w&!94~U=Q0LFe8mVdesomcSvZG)y2pqH)n1uqc`nFsyg$InSTg*Ge zzsVc!aTNCh_dN-Pql%SnWcQn#`7 zs$6?P&vtAiKdXGzKkLl}Qs|nZT$q&8jiKofpa#Dqq!gbs;QdclT#q%DWoGR@MD2GetsYm#z=);tBjIpRDaZzw%V67;-qZZro)zW&$r zc610=ozGe`UUVw_tBlNLP8BS$+y+yFc{x2|u1>U=K<7VJ{t*q53Rt2G$gf^T-SF zYFZVMv0Y}L_88Uj5!t0Y`+R5E_`j>}WJhgu4cBcQu*57LNiYP3jBb>It3G)$*CMF#O7zqo4`^VV{&r9&M~rj~#ivJ?yXrnU;`&Y8YukA^MMB zim$zn6}aGOh^pzulBtEzpHr7}p%)I;i*`8Wpwy25k=(afKGs)ju}-WuNfv#&kVfSd z)g_X`q7D=R+P(GyCw+odli#W+7!WZgv>H}r93xu`OFi@JBuIlx9QUXmzgCCc$*ZV^ ztY77a(Q7RD9B4zQ`^-HYcQQBsU=a$tDOxa}iafs+N%Cs960JhLcX$rH@2rtw>K&@h z`Ky-eMR}4qF7kbfpD9^3iH!%YKv*f{^m|3AAcE!%t*l#OPQzKsMVeAmm3Opz41dOURx*yA%j$rsF_@ z=IOz{b62NtgZapTEV~UJ@SI(LzmEFW}}*nVEYVyR!ydntPreI=E#=Or-DsU`y%iN ze}E#6?C8oA^*G#x&*njq*?`n32Ya`gE1>JN^XbEBxFR36_I41xfxgN%%8?Sy!>LIk4M*mN_R>ORNsn@RHXmvM^I(6|a8n%q;q=ALaC zUPp)5Wx>#(Cj2T|DF#C;G}r87xCFTUfo@igQQj)aIQ+_S=1`?Cf^ddz zL=xzqZa;0H!0jG-r~p~f>L3~mCw_DMd4-l^E4QUA^*$oC=(Iv&XHOx%iICJK>>L}& z1)@Kc&(jRb8YI7psM&LnMqj`h4-J@+F*;#(4b=TMR`oy|k)^<81V8Upz%?~E44+PM zG;lQtAI+7pk>sl5sq)+N^OlP{$3){tIp>Vx26Ote1w@EV?M*)F*9|_<2dx_(BI zo`KcfWu;0xcP;~+dvC#L7yVV+1*P{5O*L6cR^r8N*<}M2>JhAJY-(A@(1fVuput;j zc$f#rwfJ-R&6`ShuZf;J^b}t}cXDesM9mIK2v(!2>e&WzeotX!h7gW>lsS|JJZvg% zAVpm2vdg;DY|D1F{OY1Aj(8+l540eF4!W-*76sh{iSc^n@8<`#HQO9!*Gd6Lc6LC& zT*69c%W`{Phv=#@A41KF*T3dD7Hpf9=b@e>Sg)8+jPAbBR=U zy3}_f@fgQJK`p?xPtk+Qj>wwn0*R*2FmMc9&kf$$@Uh1aO}}e!R3V}v8r_}nz1qQ% zKVsC}>~ljhKKw3FI^oq-l34r>AtJV_@3V`j8rGFYk6xbsnF-mRQ?iGt4NSX7LiVs_ z)=rHz947BmhAMca54CXinp*nZ26=S6pPEj$5Ax#L8k+5?@euM(kSBaCoJI9Gv=KGS zqf)VYP_;L4m$@t!5s{L|GFNiGSAa>4le3PQ>tt#-F|EHW%(8VH?TuWks0~ey2|)%) zld%uJ3q#)~ut)QEs8~Kj>^yldYuo7l+d!lm;gQzoO1h-}aXX^-vvXo7f~2i-?Ea9#1p=%wAOU`kg9?!5VQWN>{@ z`z@gIGa-Agf|9?jpy+*GrtT;3-GxIKYPCG%iAazAxelCADB7%Vb-jl)jTEc4N3Uy& zK6~ibT|hKa;H~0<{BEX%ctz_NvttikXk%m8GYkjRX)g@r?%PmSp}ZZnCypB}hY)P9 zxSTy}XzcW(Q6BZ?VH?M(luy%cTQc_#!(^i{`%SG<9~Rzvf$0ySrb69kLS#P;7@K)j z2Y<<~BOc-+JB?K*QQr{7cl7}aW=N+FJz&ZGk+kLp7hH*R?H$18?ABzz98ls}6%^{U zth;TLI>u#~tId>+ri2;gePrAK^0|dF5AJ7pA920B^Fy?qYv2*;w5;b<*N+1|GPs(= zs_y|ri0duk`fMCaHKFM#=9Wn&Spqw@yYh;cV?U}}^RAk07fyUvS;^OxQ2%ZAQ8w8J zkB=v$-Z6ZLI;r<;Av=72#U^|>$ghYZK`0&fmT!?*NHp{0wbC-*2K5`skYST+bPxOW z)*TY@j@tHD=;I1AuOFgX@?XC*1I-ig02w%1EFZlc30A+3_R`Fl?N38>al*+yMnfPT z{4g`MH<#n)hfyLLLZ>O6IVo4O$~>jk+jiI`A0W7(r|d0W=%Z-}Pulv|(BmN10=_+B zf54`qkj>~Aw6~0-wHU1g<^&36 zCNp|x^=20iu|}!Na`-sb*gEbK|L9NTU>z&~0W3AzP7@rD`2lEVQPeVnN8y1ZKKu_M zG?Mg-TWLf}1T~B6I=Lmvb2=*>Ik^@#ChN9?fh?%xy|$iT6#Kl%@=gR_8%@*v#Fzys zlhv2}@K9c@ncMxjP~ z4aWoTTVUwe5=l{G(1`SMu(o69yS8GD*wzDSlO~Zan#6b(hS9pI-b47hE1lZuGm^YF zL^cS8K%7>oW_wXT(!$D*C_HMrOQID*1UIRj!o_u?Vn(db6iORd+g zC~7Y98Ge`Q2K1PvlgK59*tdE+51cgM>FbBd`5JqTt6ysLE~5k1-1#N*?a&UraE#0m zRjnd<$1KJ{7LO$wn+_HyF(qv!{5B562lZ@3B3+W1GOqcvHVETb7QZyQ+g~udy%y#Z zaBdCl4U)>BhD2%nN~h=bdlx44&A;GRJKGT}+tX5xq~7MWe&f0KCIO{MYD!}o6}64? z?@y2R|F~10sCdrX@s-hE$zRq##EDE);*d-onY}*e5;L=rov(8XDBXTaDHMwsWS5)W zb%BehT-vCNP`cTz*5qdbJSlQkly=m+cQ}#SSjxa_yVo@?UNW-J%ew>B(!67{L$@imOq=o z(By(FXs)Y5%uGJRXm}c?}& z$&~u_DMVQIkMFiW*nAkUc`Pc(S@mqyv~uC>S1pvwa|PWZc%FIWOQj0!jFw_RE(6!H zS2mSKEMPF?Y51S*j!LvNa^kG)@p&%I9pK0_{ozFTj>Uz>nyiax#;v+S>%XLIKM@2B zDT=HV;cB~I@O*r0Kw~Z}y78OaNzg=#Zkg)032Cmw>u+s)I`^-hd$C{EsCypPJn zS3IqUTCTfuG~VnSe`mXNT~!G6JQ!3t{PZ?2tS&wdgLqKD8q@uP7b3skM z1pE9g`MdJ?I4B=!K+^9qExK*&qe>237mYWoJ}~qUJyN#N)3q#^q)6uVQ*7cqVX_`U z_Y6;=_hl^Ci*|*ObU$_xj^V>IOw`xaS^B-*$}Vrw=~*`(*IuCChh4vUc61?N+>Pri z5xfwF6SiPOmNIX1-)X-|JM`E;WZ^h0_t+@VUP{*IilD`1Z+Y%qq!#4)>8$o<^YBT_ z%6yAeFY*ew`dpN|me~>O9$!?Phyc=xQ$3d;j8wJc8GQAXa+s6aHn6`t$}-wA#xksw z#mlp8q3zXf6)K0vOl5I7tt)PdYGluGdFcZ0-lzvu`R31ypC*|s< z@VC}E70t#*Dp9pNsIK%S^2n23*$vax&yE!yUfbd`51j)%Q~Ug~UqpGjVc8~Em?-OL zf4RKJBs9nMW&Lq}?o&U(=Hop6f|cL2b2q0+z!hx{`b^GxiGXUWdpiwY)lHU9oY$r@ ze-TnZW39qIjBQUBQ;NaHyQXGT({7XTdJqXv5}IX^8oC~CdXwA|4M##jCh}IZX{g{1 zw(n+dHGsnG&NEXkH+MiMTP(yC@+EoL)RWB7UK4{$%6auQO@Z25`)9-=)GksF7b~(DG5+a9342!9{hinjs*c3 zT_B)N@1r-;msLY8~tno~TE;%rU%4${wG^uxJVpzFM9jLZkRUmckS-ARZ`Ei6C9p%fCb=VFnAqpzGcy=t9nBp|GX_tzco-$zXc3e`)Sa|*_5Ggel z+$FN#!!arh;kt!XMFJJMfAPx$RHPN~Pb+}bCyd^isTUZ_Q|ouW0;QGn8{hk5mgpK@ zcX*bFZ%vd}-_+e+(#rx|5R&pq-vb200+2A#Y@4~mC$c2SpGW(Yb-8}6A=q#{A^)W>?SzNs4TsLcDS&U5w8^Zr$ zNV(kn4H86Gba4qsLh~WmWy9!7tgz?H6_R136@AL|USPJ4YoH+~wH-wH@4h@c4=B+~ z|MJJ20qQ%q;Ak42-=5l8jEQzbpx6gDoR3^Q(JElyew;1+7#5XJsexO*5mt_8b^wAnfBw+`w(14!Fu+|%@=wOuzQpNcVb)3?#8CP1$O9qlY!(S=}j zk+wR-jy#5JRuE4^&Q?V9<8O+L(1r`nmFX4KUs^Sjy?kxIHc=FUJQF^us;fLKfiHj!lfdpzitvWMF7;><%U#KuoSKT+;XCP%S3{ z*wnGhrj71IEOLhe^w}{MBuR*^uL2ToJdlt375^O^kU=pDIXm95&Ra-pkx3vzPXiny zm|6oB}_oribP^5GgFTLcYqn>#XN5-FU+_O1~Cded|(jRVl%;4bhopQyf_6e zcsQ(F5$tnt_dDJ>{RZo#Uf?F#xV)q3bPbotBIC1%x6wc>fu(ZkxsJ`J+5| zPngsP%*{BNStI0lBW!+_)g7?KN_S`Em)$ezj_EZg{mKm%?05l$hFmS;4cQ73o-)TE|sD#3MUqU(1NhpZ~u;Ul@$D}vE`dqRjkTe35- zMESIH5)iff>cc%k(vL=~CbUWQQ@z{msD`rzIYd%yi9YCYCCkCINsbVl8# z8y}iuAD_Tdq&}go&SW)?;f!}3PMtPd--a*sr1?snqYk=b=-brTxn73{9p|+?-E6YE zafWb;yA`7CSD_*rF?y*lq)0tZt4Ch$Mb@_5Nr-v++T~OyHRj>!-VBSlz8R{bPS@R% zI@a#*0@tER;*Q<4t&j|Ny2LT>8k|q3bvVNgzk6MX-jB(p?(EDkQLaM8?{N%xuaje- zVt+Weg@S_e?q#YNFH~Hhj%&bCOmZ{oR?dmW4;JtXl#iI+kWg>#fvXug0@IJ_xXAyb zga#YgvdoU{Iac7I@ki_4|8@5V3&4^q{Axp4o$^{XJ3(1SK=Q63vNTWA!GdRotu+_A zI2V13gsP|z3y+2VyC+Z~WfXpJhc?1ZO)23uLowL2^h>{>S@~pEX!bx5q+U%($I<5e z(bu)J6{KED(u%aTM5^bh-s|{o$k0;C^$umlnHbyh^_E*2 zyX|<3?dSMg2??xc?E1dZEKoFJ8%g0<#p`6}c}$kKB^lAnP^GKRA0XjHK$0%32}6|j3}jpdUt`nc>`?8L2%h|g-4%f-L<;@} zscVffYtb*#jQbJ^7v@xjbt~QzR{lTjoqae|X&=XrWD28Ep1j32n4vKyW~fE1N#4dt zh2%Awn#-V7QD!AX<6W8;hSG!=(?Wgdj5F+ z*yqpZ+WG6g?sMio_x(HPzVF}fT))rvgbzJ*uQSG3%ii>cmG|(j4)Jj4#b)o=b`e=D@rY--E~B)&&^26125Eeqcun#RX+8kPqFMD)ndU+u?D9iGs-B{*5}vU8a&IA1KV7hRAMU`^otP(vpSNuHpIIjbj*T z+eAu$boCEf3P!Hjb@!~#qUEJ;&_6qy z5Ppwe`r=Kizsn-e`a9*vT((+VRjlD2R`vovq(qtsW@jnLXSHzbR&?5IPTJyxmc^#OGIt zd?`Qiyx$8uyp(~=+xR;>tN35%0_U^ET+L&d7xFYsnPsvAAgP`3J$9j=)LdD}2(OMV zz9WjtOnyI5s@UhJZh+cLd zgvaVKly5Wvq*s`G9fXShIdgiF>iy#d18U-{M#h0@W#eFkLJ}Nrfv6(@@qA?j2SMwd zLrYo-xmz8gE@LUXO$eSecBeKKvB5;*e|+)n;PAeN_lSU+7`NMraSq=o5*BJD5d;Ds zI8P#5V@f)fsb~+B9ec^tog1{@PVScQGM{lZ8B3$S!~x*+G<_UcoU47@M!umg9T6xf zBK+>FG;U$cphtn0Y1H8L)Q>-L;vLpDR$z_NkBxF#khGFFhcKC!VhxW3nzwwqPA_?x zBv=ET-wz0RzYI=(bKi-3A2k6d&4)n@HC?L=Z;tV?l1q9vZ2(fJ>&w&L&cy5pem~YI z2iMH>dLfi` z7&Cg?M#|;S(WpVLq(3ugD0+iiA)j@G-d8x- zPm{Pkb+JD`_qD}`b9REv{A*YBAJLc_S(Rw~Phe0Z*1T!@tt! zA=;W9Vjvw+3Qy*zo0)9tH^R+zkh3{1V`qEN^~tfZnt73aZ8yp^O69uJah#8BW=|bR z`wuy{kouJ4N1EzBkN1>nnZ;%B{bm3;OmkI)9CfuBCsmgzhXWF^AFs-<;t5_}jZH;%+?|2%M+ zSuq)x`QNC0P|eq%L~fg>s*2(n>mZ0_2t=MVJpoIT3!W!G;GS;&Y;Ymcy4@O}v6?OoOSX2%e!AAh7}-|9o$FmJ9pE4;rF=LKEHP>$2lydrKb9Cu9VN2JIJ#9 z`SO}gD(H-7Tp-4(LiG^kxNN&%-pwADWL-Samx2M;U{5=ZguP3A0 z$R~|(IKU?y(eM3z<+m>D*gsa5is>wRVQl6p{?(s1MPcu2i!a=^6v5dizCF8$FC;UE z+A7Q5_><}~79J{EKcU;mLR03_(6=sxZ`$Hn)KT7Y{AzNmsm zcb`|2>C9sPsA8wbV?KVv4IJ7_<9Q1;b=eL#h;^sWjUxkX2clpJ;*4 z!5|_uAnxbu+4Q$5;!&lDV0oP&^HKW{31*FKtGXapP$rixP0S7Y_s#Au$%|)U$)90=b#eo2n%UPfHqo%U zX8cOPUGS3GD3nIGOBnG+pgLe1yWvW9Dxhzg+oEP(%~ix_&&M0j#}z#?YB{5vW)+(( z|5rO+LrU|`Q`w+(mNqEg#<#CUP4i6 z5_&?BE}hVO4}7_wXMI1sf5N-gJ6R{0bIzK~ZnO8yp1GoQwN zMzne`BzO?&vpp>%nH#VjFsn>OqJdOiP}`8m`mem@U~>H5+H*2;>i?;I_~&ijjsK~A zC!-Sk-uWSNLG5Cs{CcVqNC5IWw^h}p5mRKIenuMQSrQO){BrCkz|!x; zFwu9v-=h2Gt-?#qs^6o4@aL)0f55+UBK|z}YcTOVaBH$QL7@HfT}EK+^@xFv z8Gm~_twNs`LP8v5W!5YfF#- zN(>dP?5?72?@*(s!}biO9tntN68VUbgvJ4GHBbdz9E-~ZZ;X}s?f(6lhIOr_s?rKL zT)VM)Q}N$>9u($4oul>9v#~M@64_zH4IXxyy}sAP6KZbn<4rSz#lh^CYYci`tTsWFj>pb8q6I2Yh2qyU&D|9 z&1cF*sbB57<51l@;}x7In-h3_co-=Bt8xTIE!9jDZ1Dy;g(?4mUA$ZuWU@wy`KD!f zC^=;&M;i#^-KG5DVQJcY>&3Px$4xS_9-Y@?isR*=sT%bpQ$jd3>pn@&TEcc$muHq} zeI9x5%?$LO!(dMTXt9wf#F#`(bGd{|Lvj_BNx7wncx!WJjefW)XHbeojiU|W&n}XR zZh?*;%mjEB>5*LbvBNanoO!Yy3iZE~4?1Uh({<;kPO>pp1 zqUv+GTX|F~*rB$N5d5O1*8X>!_UEY+>3}>6mJdTD?@u991pW|8W6AtBPx=X#>;V2A z`(F%kr=$|2^3v@kBWG^_{802%OS!Qkx}0)@6fXY8J%HwQ$1vM<+_VrGN?OiWOMHAu z>M)Z<;Q_Umekzw~msU&$ld^!?9Sj|h#x7jc0hrE}(pNYwTh`U2aIsl!S#Bwf@76D3 zUK0W}F?Ds^iC4IiG9gLDmAa4Q9Xaf)qK*b`&?v$EVKDKW1>KQpr zf++$7Kj|}&0DH-tGOfXEWDEaWcec}`6eSl**tf{xuOsrB+};AfEU97rc4bnieHB3x zCr?mz!D-d6qm6NDdInZj7w60RS^wVOhaTJ0(xhS7RBPX#375#-&$PlJ%tVHM3WXVw z3rcbbfD_KFntg{0i42U44*m*i=7Q31KI&1ZD>x$mX=TG3_df43i-T7G=L||H{6~uP z(x^V9Ol*b~RIJvF5+6D3l%^;FzcTq(tNHa?wFSy?mZtqI4rTBZVCH>=rXul{qQp_& z_jtqY*nf3Hnwp$iaV=qiq-6K?5x&_*&q4xACH+(F-Et5Hh_HyVn{5fGcS=rq0RHZr zm;8;&`1Wyd!Y*7c;P}(XnO!ZFF?G!nd-_1!tJ@_P^Fv>i)3ENlf0brQrm2=X;Y?DF zBVR?z%M|Qen8Fhk=F*%0bw@JBk4>DVW4}M_{z~u4dUUyq6nXmZKrm@8^GJ;Jr8GnP zVknWC$_q(ySPMYj|Ra#!$u8I?WM#ac*E>!zus;4p z5Osg#voXWU`uNtdGHrCM=nb-;T>DgqB(H(7RcUQ@V?RJ?-G(hiayYGO6N%?ACvd8- z>~E-6@TrZRg5}vVi0?qB)^@Q6+Cp@C;2Yb zt-jtW<;kzl@VgHeOpg>EFm+DUZE0$VrwC27K4sF`iZHF^OnR4%O_~4G z2d{)~HZ9V`^~3QyXMYC2Mx?p(4d8>pPPe^Tq$^T;+Uu%= z`^EC*HRPTz#nRL%-qalu$6_r9?$x~-gbVov4LLskFB@hJk3@w2Dm8L# z>YJB%^&YcN@$4U0I!5CLY1+R-9(yW44b69U*{67SY5D9&tkIaxfs~|QYGFT^9HCR< zOyQ&WDt9Vhz5o)3aeyH|2xF!a@1ernBKH=AMLWYtI z&Y|P^7#ZbzOuOPm<<{deMd&l~Y~`)KI*l!@H9;oFe?LBY2B$h?`LBVE2#(YM{7ZI3 z>}jXBkGQbFK}2ZWBVGY=L6M>H+gxn-ZYk;dj%*|JtdSfxu6g|(2Qt^&1JjKca=N|8 z5^*K4J>xV*W=E4nUkhQMIbtk^X5^Tvleh&#yeSTCr68wPx|fnymrP8lKkM*oXw76F zkS}-1!e744Q|?s^5cSIGOP-h`g6bwb0<*2ZQ`M9l0bCAA4upOCVydq-PK_L7@o@Wb zpU5pGF6WGeOR?xHrnfD9BO2(ea2~PWIaI!`kE=5^_+kw(lxA;O(!(Y8n%TNFA?uUb zz7uFSVFjTdQ_m&f0#=*7o9rlx$uB+o?_LB&jf&GRZd5cLc7FF09laV+yr`zVX_Lnd z4haxor4qZPln`M)B_-TucK>OTo}(qa+se|BKl@1DJp8n_J8DY! zsns9Esp*Y{?cBAUt+wHiITkjBT*}$u_AA|k^OofEkoTU!k@A1Ty+ESDf~!=kND@)=}!3iHN3WwF{p19-7L~J!5#Hf;bFrT!>UaKvoxpZi=kQS zXa%nOp)c}70YkIDxJVKY2x(VTzIW@)#@zBVMdhrtfb^lSSkt()zP(V0 zqL0r>OH)l}8_0K}h;OZ?k2enYJY4+8&uhC<)?e3;gP3-Hb%StySFS4`oH?OU@vOz> z0%EDn0dg0M=P>)IYO-CiA|9_gzR_hj%fnF$gk~Z-e9E}WFO4mP#x9In3yE*FedOs+ zoW(vy3l*2R{o9dBLw9l>`RB~DTcN{lq>7@AU7@u92gkJYA0p7C_=TLvXUYdz9e(vG zdet`Yl>#l-e0WEX3`}f**WeGw0 z+j>^YCufESJ1$!=4UwVpzQU&l%Y#+PzZ4N>^(n4-%0d4tebLP@?~%vB7!dgCi_9EH zT^04-HVgJJO|Pw17zPFyI#Us_=q^Zuk7+xADupA>cH)QgFst;G|DW95ua8JY?A=*ADc~Q^JxfH zj0vH*b~bF%MMaIKDu5N{dxi74&-unRYsnc%-vSEH9E_Rv6V-R^4-bbdNFW90RYL=(3(LfRt1NTZ~1rji;ikMTyf&M6KSMN^$(?C)amv8mTQKlDs`ONpdlob? zQSU81@0YPXHshW=_P?MYv_TptHDLm^P#Ksw31}#K9diEZ;SFX`< zo%W;^9&y@j4nOOrqCQo1E;d3vy7o1-Pwp{(U2Oj1zo#Q!<6|^-?IluibuEeHgoNlY+GZ-G zpjTIc3O&1B!1mQ=2AFvCg#-3Mx;}q7)#02oGp#5Ll=a<|klJ&J`6vM!l;>2CjRv50 z`0-~!ny6Ninm)(9AXY?}x2<5G6vH-7!3+I|3wWSl8<@Xd8QzN-m6<`W3_r1&D?Sr6 z0LQTWPT8`&^g0Pft)9&ifsHyMTI~HJ4xv|NU2njyqk&^$cKo$dL?M6gk5=Qn*e8Sf zV5Fm5;CVhU-@fSD4qohL>klh1@4AgrEiBop(~UQ!xQ;P11K-!pX(+Qdg?TCVOH zboK7F9bKA2+ZWbv{1pV(mALBl>h`irnq6BhJ;ASnU}h2{b}VP%99EWc(}7cPf==zV zoBi;`f-}w04}-|cqOO>YZAeq;6=jQkZ6m??#qf7MP%xa#&4esam=mbhrR=F$c7Qh#JQ{aQTZj0B8 zh977RM3CQZd%dQnueC_Z49vj`xDp$}$ed(KRJ3+Q@J2yDh!@<|w)y)|F-7QG#`I3g zp5aDuG+VMe{kw*5D9E6f95?>%BHdNmHj6=23-By{oq(Hcjo$0e8xxENe3c&Pinj(b zcViK7jcvU}K5}dSbo1P3e@o0eDU;2fJD5-x7pZa2r|0#wi>WWu+FP-jYC6@;0mC!9oIsIL z~@9ecL0HiDLtA>R|! zW5IZ6cZ+D`u*CitQPjn;ELmV$D~diK%`T=6fOuL4HFZNwvcuL+Q0fB;_yf>;tchwswydK^q$lt+s2DCgbA6 zRXJ6G?a#V95xe4A@XU%jEze#jjyeEUKsMp6dW-zT;JQs!Iqjfraa){Ix_N|_5v;#z zvF2etfH?iZscq!S#PC8dR`N<3f(mggjo=g-5OcJ;tXlf2G=^?B*=t|FL>(9MZzy0l zIdnIMgKrz`&>qSI`ea^~os^xjc&H*)V5%E z#!zilS`SB?j11caO18!VMDS&OwqK>^vUA^~f9kwPhv3}N*%~i#YuB`N4qHIk8k2oi zN9zMh#Mw-;o){uzVoC-fm=2$7fxok6p*8RCVT(MfOPZU^T@LTPlBn%}+^;wopJd_| z8*|r`NX06(xJ_s2d->K4zkl1UI;Y_X+L4`xE<6WxK!-GCV|jfcpP;SwN`D{{Hfc6ve^Hbr3BV`|B1de$wB7f9rwi z)s6;6-VV)Yy)bP=k+2M5_cKx>;tOHuL%4!S_V4_dT)-TmqI z;eSp!XS-e*NvM~>z83JD3@if>h9&HvC0c3bQykbe>fHXr*hzV<@yWV5K{*|f21x_- z77FNEC=6*+nF?-uc%AS<6%uCP959QlGiyTl|Jf0T`E~_y0zjG-TJ8habVAn0!+#~= z<%ReI)BL)gVg{h}fanqE#{;{&neKs+iJ1h?^`8zuE>CSv0#SBoFee*dLF~n!^b{`P zW!-?F-slA{;IXiCKt)C2aTIQRD?`4~1cHbIR!3M+HJTihUfeYZgPqTpHUk#ri~%r{ zbrgr1zp#T${&DYO2X|9!WX+TWnT>h}^IB06-@2`#a*y#{d@$Vq+(fceLlw?D0QR?Q z_DI~S3T^1Cv}!rUKf6vKGxwG&b>tbu{6U0sy+YGxrf`a9Jf)| z=IPr(-|5@ou+GM241bvj@c*33^`+NARJmGiuqqrds8f8<6bb0o0orC>KQb6ssWVp+ zv6h5X#m@Pw1loP)M`YQ4sdy2aQ(R6@pAuz+TJPqabkry-Vk+msTAI|tkDNpJs?mLT zW^iydfBv``^Axv=m!N%55Vqmi=G>5I?VVoEK3mu~;S4querI2dj@jlMtr>pk8PpId z(Q78Oezd(Cd)|U7hxB{CN!OH*FZOUQf?ZiLcb8yaGf2P1bO{dE7W))!Ouq(m&XZK})|BC#y7>Lu1*!|rcYX_J-HtDx(mKoR%(HYcqE?I{BJQ$Sz{9CFh%KroZ zcw~fvufqQ%pg*xV!WMg4a|x|Fa2!ZIkc;JvAOBHrePz^y5R9DH;2x#cp9z#^SJ-{4 z>~;a<9$?j!4UpYqrKN9^*CyOv5Hz}{L(O>F~&_cD=L0M_`~r$8fc`u%noapkAmKk++zmIj()eFBiPWTznqtboOX~+xQOzUzP0v%C~_ds zF_Hupi&e0fRVgaSiZzE6vEeVQHlmoLVrzOH8FqB8<{LJ089WJM{bgK|amAOfmHJ8hf$j?Q6Tn~mY9u_!AoY_7 zX8&Zl&`aubOSokhy|U}bp_`5WiXXe^CY$~I^xN&a+c37^-hQ#lCSDU~zu2>`CXx6` zH!3&R1#_eH{kL)Kb|o{+CMLD@QLmoMmX(x1mKumqcnZEoKS186p*$$(y?)vcbk5iDHR|7Dbb9C<(DT!8e?<+-9YEzHf+w+PK!C?PE#`BxJlJyKFMe7Ijto^f{lr>>OTJJ?Mj+FUykO4%rQyR;Z z5yZ7Niq112gYek_PQz%wew4U1e<}{jcb2p{l30_Pix}NCg20NDiPTMX2F~d^MJ^rR z0^sK5!(9zuwD9eD%G1w=O+sM%fo@%G=?`qF3|DouePeL3e{(XM=|-W1n{K4zK`q=xKK(=m!4z zaPQGgQo>rXBwDwX982b7J85kO@=ZCLF$2vwYO;#=d2zEESc8i+*@kOX_OZYxB42R- zKFL?UyP+`!16q_Rz`NQU#bnem2Q=E4wtI!KB7pE&<3eZ@t)YIgT60ATj=dut(5|aI zf8X0fMq%%4x}$zXB%m~bCC!RjpjHbsjb{p zuP}@k_8ki5@XVIY`O4KE_dCg5C4xfD{#K%xTC(e1+`pOwdQoi;ll43hZjq_SX>rN5 zAy33!;n1nG4w{vyG>;Q~REP$_e6$Mt!9=$!V2yQMNs1efwmc6tcm9GLJI|B}gYvQS z6=_wDa9~w!{dp{3p&Cm^h#^hhrl`bC#sH0V7u8w(9y9l*ndpXeOvGyAGS9F{&dT+4K>NkEe1>3oU8w0&JS4fDB zIAOW-Kl?zT6#m6ce@FCXirwDg?)aB9-MB^;xHY$|79+R_h`Fzuz>6<0wgi9Hl+=vP z;+lBsN9>VpXp5%afAriIaF4AP2pUCxX@-)Qn6Vexe2z7lC`V)lRn~DJg;1TQlaIg9 zxv(CdiR`vBi1yq-BAMAP38|>{HJ2lP#7Rr|K zp1IFpvOE1h%#Mrgg0`QHS0|J{NKI7|M02Pa%mFiykG4inM{JHK#YC{)c6_U&3*}8V z=9r4qP{Cr@4|O_JWq#>E)}z>wCj(}-{&u(y#9Ff7h%XWr=oXecO76)uwL3kj)_Zu( z5Xou15+LKSp#3Ut#qM0VWP6%>j3DU*e6}(rf0@Bjk7Gd9bB=%$VCMyhfsp6oU#fES z1D@HN0$d6(bkJs;rDsuNjOhIpvd<|?Olc!QxLsZSJJ{f~d)e2p`0MQqilJY}b2a#}#q&h=`QG`E9h2Y+=7Gz{+FsHXgf`)>HtgTS=+9zN!M zT7;(qmmtsp{b*G0+`;3*b4i8qXV>=~iVEXawbz+;8j{e*=cnOsswqT+h%9UjsU)6Ir$jBSFgLTA-5~0x7rDX!JY!DLcj{W?U|b)7e0#>lszJQ1$2H% z1=5BG-@G+G`S_N)H@qhS%V;j;j?<-=dr5v zv!^^X@2%BA7Dpowvdw$02q)#|L<<=GCX#i}cb_+D0X-KX;|5VzK#d{bSH0aJR)wF+ zZ;Y3JTGNHd-kfLG-L=a=CMQO$!8m{isVg&M_mJC5343{|fLlk`Z~497$N`0n-v|$A zQdMtBUAM$(bMbn#AA~!qlS|bx_jQ6Y%AXnRxqygMoTD&}S`|>u#9Lw1Xm;Ym)N6=3KRJ_!RNmTPnw-(DY)TW5!tdmDxS{`@H(JiJi0nx$Dxi2zj4e zZtW93lP^_hp}pPUNYd`kgGgC&IleFGoQUXAl7VIJW&&`WA`pGatGU#l?BdacJ+r3d zTlwT4DPh#`nHREvFsDh!8C=`(4k@2w(Df)xI}2K%WByyr>A67#?P6hL0JFhLFE-&4 zJ96fU(#MPdP@)fs@lM|XPdQ^3zJzhCn)KE!ns93NSKm4MTWxq_Lhey+>^>OVQGx$A zM?GF37I0XMyXTMh2coKCNPc+;wIq%5ChuP%-f>Os}X*+A>WdJKc{SW-w`e@ z|7V@+?c^ejnfP1X_FszWlii2d#qIc@lI}|QAeqx^CK zIsMK~c6x-TT+iyRro+EI3&{kd`U_vE$#2HB*1SI+`b;E^qsmYlJK z843FfT9@^0tCv@OvQzmkCBbH6{i)d9fz`}Kcj)y+u{&UJfY%?&hYCHo|LcA^7h7!b z+w-qznw{iDT^U=m$v7uXf)c|&D@KW(Cr(f$;q>OjTGk!wBk1^B_@QmD`_;u z-1ynYd84kDjcU9Cb-m+*gI2LcYO^L$kSS1{ldAMg@1Odz4ChN^fO2w|3hsr-suSwt z^?Hq|lj-VNmZYhVjsWlS8|VB=LsC|JC-%`S$N-My?@*2Y7B0gx_JXtU68k)Tbw*>S zPOt+^LoZxzk%AfWsiSa|oCwl>OQ{~gfpW!|HiirlZc6=;!1R zq^5oK!QDey@)paGF_A_rqw~hSJIj%4<;_~mj?fCcEvTlIkzNp8{>1)Z?psru`70TK z^)NHVrktsIudB%LKk*_DrM|N2fqoAh>NsU{DY86N=Wr$rDftuMmj>~>e?c#Kpn4YJ z!MZ5SXgqMr*?l12tl_U4GT-TRR;6PV@32t9Y#>_5)d~+iebe+Qmd@r?`%BHPvP07J z0=2A}^0|Tu+eajTgw(pJmtD{J@B??UFk^SLH(WD$xIesWOBf?2as3Fk#Cl{BO9#vX z`P;TTl$M z4&2z-pkaGrU3U1&=xC{SJekBg1f3ol z8q6A21A|$4F2rZJtr#vu>_msfL&m={;D#d)6P|*!Xag;LUR4z%Wvn(jS?!%}32>?7 zeh*4hDZl5s9x|0YjIQ&|`SIduX|_+Zw^~`NSX0UX$Za(u{62Mv3Z^wq(xTrh&-a%p zk%S-H=e&)r92FKy)3ITCvHJEt`%6JaWdg-1 z@rDd%nLzHlf))#KNvHdEUD`}UM2$XvR5}l9@@dLDFy(IBRMG)Ddhdg9RCmkLWY*7` z@H)R%MYA&-|5(bQi*Rf(DrS3ZjF(`aHkYJ**O@XokL=>-U0De{S21?MYt` z5{AN>#cN{2L;v@qeVby^z{OeBQ&8M5iDrinY}wV)CuYnyr#JrQcV&bCx+mxA8NO5% zQaemjaTk29S}2+-KQOYdDn1~Ef`Oz`&1VgE=yc%Pvg(JA_mTqciLyKI^>OM!b6zi| z`l!d={-0CrpgN(Z1JPd{uG$6rYJ|O7$tD&iY{xLx4V50Q=Ul9S;Q5eLn}A=I{DM%Yx@n>iXXCu^ zdNH+a489-qi+=ke!O39scj@Oi4+EFAOX*})heh?85SwRu+*<|R);8wf%Ewz2Z27N! zel2ReM}@irp4zczPH$D=2Ff1~l zS(qB<$>K+b^#{olFqUt2c;5(9zq>lNzn=+I{wMKK?{JbCsb01e2q=xYt}b;^Ad3 zxi6=uC@EG^o#Uho3R2iei;Fl3eD<8W=Ba@z%+k6K@}jRw0X4};4yg^iDz8?cz1zz6 zH1xT0-nb-~X-%@Q1Y!CQ_*=-^;#&2#6^Vi?&SU?D8c-!oS-$dom!S9ugfk&)Xek5C z)umJ^Ly2x)f!4ioFlb=Ed9RR%aM0Dd^!KQIV-FErfjWbuaW;0oqn0j>V+#wGC96#3 zDu`1j{|T2~@qjItClMjOy(wHWO8+#<1wmZv%?~4RZ-mqbvR679qkMeuTF2>ir%RrV z8MAD^43{3^N$VzW0s0mcJnfVE@AkZmwY%`?HZzaZ!U+&{4Us8@QVLC7&FUBsPKFLT z8c}*(gFk!lWko8J&f%4Nie2BSf$)Y)xaCV{VtIYkrldNEZ|*MVp}XS`wpYf>hl(H| zD0fvM&jpFMw&$<6m>YaQ)7c(zsO>>=WDTTqSF}7{-d*r|lsWYnLtmwF03oE^0F&#^2mv{3A#CUk(>w>IDU-b)9<8j(R zJZJS$=9)7?&16X+MQJEphB1553T*Y)N;5K`?6JIQ=4pv`2cA>YEcQMq6?RAKuT}dL z>y*mKc8e_VY@k6zPb6xN<#$+|*sg%Dsn7M56D{hq+^99Ou|1>ey8H0_`={;?@30BJ z4kl3T>CZgUV=S7&a1WZUF@tBxz^5ygw!$-=mrcED-1b&|^`Fu{y_zETSvAUvI9IX#Jfr;*z>(7Yg!cAkqP_pl-*w&2_) zj~ph;qe@*vfJIA@vx}=dtV+X$2)Vr%iis;Yl7Yt)%6^u=Om%N1@Tz7+d~%KnQSu2E zvH2*$f19e(Gq6U#P&mbmm9)*C=5}c0A%HJ3foBG--lJPUoiy2|XV`0j{STzKLCq!$>wmX;<65&K&FSnHv;R;p#cW_2+oZ!RnE?sag~`h5fR3qO-n6?S)P`Z2O- za-{f;1IOF1yW)i!AP6Q$a-}7Fxl}zu(6oP$mRnMjw!EB%F-f*20GiR94rF;ttB zl&RzZR@(75=CZ7B3DZ8L=UsPyh_TXT5u>GGzVq{5ykmr<@yXuqyxgxYMaq(HrBCiZ z6x$UkI~41#cI zu63yNY2_>esY77J+1{>Rj;y@Qvb=KW{;5MfAc(;;@J&3^Ou$%6Es&@7d$HD)#6Lcos0}bQZ$Qpo#5On^{!=j^xIvAEd-PFWk4e$1H2+T>W4 zMD6zjD(zfb4*x6&+6cr^uI>cf+g)+z7`iJYoBcXNjh4@2f#LQh9tA{+|W$pONYUG z>_R9`fB%r*UNY%B%)$ls#xf^~BR-Ol?%WQM>!H^^-|4mrtMnXj^yr7d50`UcGxUU>H-dj|9;iaqZuqx%eAb*s+6+EWFye4mB zlSgiJ!KP-wR3tT_sI}uH6T;GT#=5-_-zbjZuuq%U>7uq?aqz>aBI0 z77Ve`R`1edTMCS7I)J@e;=O)B2U;Np-QRJ9^C40w-1lol_{u;9&40x3NSL4}v;VNycu zd!wZth1KuI@J;%>M;0~<)e=Xi+JYhbrUOchQmV_G(%r{5{n;&^FVq}w;no9C3LB2q zj_(BZzypD^o&9mJrxHnLuYe1~H-Uo28@rj&bwPpLwX<_{LXWO7{w`c?Jt7OmD@M-6 zJBCwUAyFOd=^ZkC-3HLmVF_;j8LZF6>oQe-V$hGk>>g!Y*+jfDrZU}CD9PyC38jp< z#lcPngO80&s={pFwlIhF1&6pI`;_yk1ubBP80+8A_bn~kI9}32)}YO2adoGR*Nj7h zCp$k&$2JD}bK_&{Ifm(o&DnZMmo`9p;ECaYXx&J>2d{IQ-TllPpEH&kK&}h&Mp$o! z-eRi5p#+hE*#|{nX<L}4uCJ0y zpq$JPHC_qF3aHmNwoT+r$~nIpGSnmLrZ|(6f4pgcI{7dIo$&e*Q$jbm1a&U{Q4= zXHNsYm0>kQg}v+@(S@X|j)wJx^6zc<6w$3t=|z^rv0~%#mhwQJ2Ku0WBPUjq?1_&h ztjKVsg~#0%Y6Pp)kP3}>#geW5Hw{($sRc29*19l?%p>8W~lV&QgyKDIa1!B;xqPe z*%-A?gW}*6m6Mj1hh^2Df=#$+j)~`MVn<|!9ERsYLnyI0y48n1aX#KKS(Pd0yz64R zYmjqVh+EN|ZHE*XC8et`SzdO4kT|)3oaM3izE_6ykM^hDo zvNDqbBkP)}WK~E(IOfY%Ai#gtaH?s@=7=cFZnAx(LXPWFnl~p8n(hc%H<==q)&hpU zCVwXXkV0jfCpfOw=#(f-C@&^{bty-b4+|CwK=iu&5+&>b5KP6W4G4T3J|4JbRD&Qjzz5+p!%Z(>pIUmw=O85EX+L(*jW z#e5UT9wDtX!1bQrPTfo0~;17HtvJSXS@K<&;>B z*vH`7)K3#ZC(m)KYKdVnF^uDsBdaUOozQXQr(K;Uii+A`JeGf)GI=QcSmi z(_+pak<8%8ED2EQ^ZSC10aR7Q>TM`Q^G*FD7nGcvQD;21tR5h^S65olcY4SO&oKn| z`g}$w16;S#+!r$3pps8S%Vr>Q;p(yPr@%5X%CA^?<@yi5`8)cOayVPdaG}^h=0ilJ0%KyN{=wyB1}DwvG?*+!X|O>eYnA&!Q3FPsI}3SrN42UK0I zg?LwA*;CpfgAoS_0Et|ugJT;7IbwVDLhSE%;+N(WGcM*osB6k7%vo^i>k?-|U!UuX zHZ^B&zk8J?4X)7+L0SMJR- z+nyt%o&5sdTGx3YTUuTPmVPgxWYK}%w0)lGKwwfit`*ZJHnt9|&-0%g>`Tae>fkWv zs%_dz-wwwt-TW;7K-^c;{8R$ zn~itxE9<(Gx?mBLe9z&ddGc);6F8u2tkWlpmW!>DHwL{39oF8sSLh--hp|RL;By}@ zYA0NX>;|d*K;~3Ex7sAaYby|9+mr^58mIt5jMv42lBmCp*2`3XPUIL!6H)s0`dt=7 ziK|~_z8n;azLC1e!&o=`7FX9&U~J;7>nY{+1>i1^R{+x=m#-FcCpi{g$3Gb2o3qs# zQG40Nkc;gc*$Qdeu!<54cFinPvXucBv97VqJ5u6>pj;h}x!;$atft{kr)+XLL?soD z;^2xxJH)aL>QAtorELs5r~Q)P&zHoby(hFP`pH2TOzx>IJd^XL(Vi^her&2-+R|WF z2iR4zj2nU7mG=J^kP*<9T(CAz-$ek0N@yZHkS~n|jUC8LDW0=7sbc2V*Cs8}-=rVO z0<8A?|Mb?_)@f|oVFQ20?nQYPLA)e}oK2eq>iXCvlykI*3TL-bK}Z-hz&57MrR%@E z1y!P1to71&Z3OSiak889w0@K4UG#j)^|cVRm&`^}`dMW?z>=lQXmSC`AfxRgR9zS& z(GVw6Ps_L1SQ<+*$e_XUK3|dAtz18O8)Ze2@3ya1$``W0vgpRvgMeBpuw@1KJtr+Y zM6~~!VQ3Ed=FHL?@&TE3yvv5xOVdq?59latPL6+9>R5tpYc9)_XvrDxbZvU7gwacL z&nQi=6=9%v(}6vMzk40moy{h2Y&R(7wg6@(;%FULd7eQbE;) z5}L<{fXfOwosami-VsIbu1scni$Z4Uov2uCs?)TUmE^OMN|CP<_md5r>ji^MYSP{R z;dGWM7=P7M{HRv~=%2N->@N04pWM=+#p;9#TVOO>T4PlBY~v)yD(4-5Z&%ph4CHTl zW{u^$9-n?&B3;+Xui0NCa_K|+W^VqcBJOB(x`@?`g?Bg&q`bl%E?>J9`nO*Rn_@Cv ziyNka3wQj`xbspkE86fAV774@dpTFanshZi9k=f1$Bvr-BodksnbrSDsjTBc)ZdZK#^^=px25OTLfu zf#V|8=VFHEreu=0KB$l|5w-T_q@1I59@W@Qi^UQqNiGH@(>gB=uEr1Gi8m1Yyei*@ z+miQ<{uFC@rK{{o7lI^y#DE7y`Uh+P+Pr!(7%zBBL9*M6@!hAO{Oh)hj8;N{T_cax zAETmhChOak_ZoZaY;^dZWd~&SY)>jqt@1$c8`o(6iNc;wVn3WjT8Dd1*D~$Ij*?Er zA%RVI&n+EbPo->Y3})V)fc|u!pSk~|Wc-B7e$+YaYn0lZqVaFe-{ND*m0$Ihv|o74{ythv4>=C{aDg7q8AeRoac+dUC-x=&(RE}8~2 zJ$iN2A$uo2>p+%aG+fAG>?;Q@*}61hdT1b*F?XyMJ0-w(FrydYEURE8`EQU9>C6&2 zjKeXY`FP8Yjs1(_ylsI^9*OIJLz4OwcP4A26;A(>=SVg1VK z+cPg_$@<}5{OSDia53;~-vh0Wlp;SrKy( z^>H$WbwZ?E1bi{bRX5=};PUUsw|U9k89x;xy3gAcBceh%0Pp@y=Q9X*7|7~jm2mw_ zl2mpG@yJ9u>D5zS-te}|ea&*y%5OGVb3rE{5?)eLfq00|610#YL6FIzGffXkbOzcb zvJKJkS5{ErL(FEzB`7W8{IbDvPlB?%Ol>81l8Uuim?n8_IMYXbuQz_C%rYb;u6`QG z;F?gS6Jv<&Yz=?Jw3Z+-l&CAZQ4CB}d$L{fWG-C2Ht%8^6OWL9U;~afJ|rfq?q5&O@8p>b&&c?cWk-mTAtp>a>_Nbt02xAp>a z-N78Wv$&Vre?1nv_A*55V*ad*mYA?o-~ODh8oy71?8lm~56WL`9(xsPXD>X>4NTHZ z7wRX$id)BD(EMjxhWE?LLvC(87)jrMRRbnz@pxE>9 zD$7>-oX8#dC!scVC4H@9o|%3gC#Y#3Ah4Y{d(W0u&6BJnXEZC2oRKu?m5S>8HKqK< z6sDXd-j9KW&)335?XxRo;hgIUgz);c&K3jlERWIBY1ywGKsZ~gmM`A`RQl6MdGdM^ zL(gAUc3`^emrV-g~}3=c=l z_qsOF+D##U1!9|!IBT)F75&1*3X{iDQpH?h`=Mog;@#cZgJ6JDyd+y|qO;HRENbc#CPVI!~zfS*A|8mCwG0v7`EAAKa8h7hjHu2}k+B2BhZqh|4DVCQhTmK#m3Bh>bG z`h~|fWi*XMrb6O#>rs8MSE4A^tcyM*#QSMal~js-5Dq7AjUll;U}f1Vx+$~`S>`=v zfX9|`U;X}6cxD5~t4emrv#eX7<(~e5D6OFi?e+YUS-L6>Hw|?=S#f_--Mw~u=**36 zR!dT)$A`jQ$J+ANj#$0jNyTxG2)a2h;4G})Db<>mxe2&tMzc??G@@eEy82R77Ucw5^kjg zyoclf>ShRCbhzRl8fezZ7~gQ`p`fS!OK#b{q=>|Ae{Iy{GfArKO&1@f(UZW|$)@#9l3b)K zZxlnLLji)i>EyHHPzUu^u7dL7G<8a3W7ftjuE`fVY#g#+C^5c~VHHz;074go>^`RO z3u&QC{-N!NW{C@-r?{2xPIpb{v0TT$>72#NQFBXk8+xxZF3JgwQ^bZB@f3e`S`7*SUPx= zK4sYyzdki@yEx@K%l;j_L939rP){=ua5 z#-?N|W$VGdWI1IEo_aiA6c%)KYY>5_L2adcK}UE{q1GY!x8RwAnWfx9Qkj0O=~8gw z6x4%^Kd(b~WFpL*()yDX@qfQ-u@J3u=XYn~IQ@vgbF@a75U`ic64F<2US5j>VgW6X zRg-z=~t$ZXRrT%U#58OPriQpubKMhLu(3RO!AN5fVVun z;u-?hQ0TX743iQ{6(L>wtUt&an^nZhp;fmR=4k5Oln~7FR1GQ-^+|7vWw-4MhY$S={N4(e?VX>*kL&C8_5XQzwS|--rd;!wks8 zctb`v06>?_i7Bi?K-{z~Qhb4mc!T%yg|Ch_o1^@64XkvNLmPJN`CnFKoREXzYnZ^pjeA1#GvZhvK;I3 z(xow?hCb!ToSGKm8sZuP69WW29kF3WdMQI^Tkt-=@scEK)FI z*tct3n8HfTt(?4OKrs2|OO<7eQyJY{w(ydbSb?;1_T<(}{$Z&4T8aUpz^%L-A38BP zmUh>uXS-JbQI`oliLG{%zis`OvAAVSwGLYUC;1@<`symq%;PPMMP)ogDEch~72o-NFlHAADW(6v3hbn$nS4w`zSd*!=fot==p}NW;UqJkaa$eFzNZ-XkWeT|g-h9xd_92Z9qvor z0B}4h4y=Zakmm2nFE*^%rg=sEYNrGfQeL{dah2flNuj0vNkvbOB*6!l`%f^I%`l`1 z>Cm@F^o0Kn)z72fJ`j*Ip_jqZmxT9Yw=7`w|FV+b5l0;$9w=4bpMUz#{7-5?<^BbR zAocs0wD|#i?&z0DG=kI5=YA{C+!*}}wAjGQ25okR{`3DA9R6JoAll^dQqyH_;1#ZY zC|rCtf&&5)Sgl}oO&FiY-3a~0NZ`d|X@{P2V#RDEE|3*Gz z7~oV&ZDO@hl*xr8FiHFCHDPv0Dr@zA+kE$nn_mClw?e3=;tyU*Xg(k(;csGrR2FD- zwR^w8DrK#6M;r|+m06}3_509oFz?HZhY}dzD~I~5DoxBfk2Z3v;-;3gIpC_&?Et$H z`}Jj9a!|du52m43SgFRsnQB#B64m~H!)5s+>_Wpjt(+A@jPEa=D=dk|3Ih+kCC=ZN zLhE>kxK(}S@(OlUL&XhNST_IMoq17!xG9K<8Q@$g4eDRnX0#2Yqe}v1|Ga>(pRz%Z zFbtwg+7srb{~5&4r-Hzsi2Nl_R|`5oOVO3=_O?94S>XfkJV+284SV;710M{CmQCY# zb}*h(f@b9M_wTk?UrFNd43*wFFoDrAzle0i)q8)mnWtZnynPz_aO18N+Wl@542?<` z%Xnj$qDux#ua}sTmRrQCaDP1V^8j<<>h@(K2jj^3|tUDTY2F>kRp;S(@Ha)-vn|n5SBgy3gnVQTIMPl0Ug=+WPq2#LB4_HrrHSHqD8sI;Uo-Ax(R6^oXx~ z3I|UD>euKWrfGM{oh&>TAkBmv2Fz2yoW$2DB&N40`+}EaJAJMov(rH2wW{z!s{f@1oYLi5U}D zdvwe@s;Yok|5^RQ1dFFS9akXg4LZieRKgz8-PQS`ZuwLhV&QG^9J#G_zuy=a;{3Bk z!aZSp`Yoaglw)IK0?E-~=ou9_S1=WaL&RiB+ExDGRj3_FBx4R(lJ8O@R|KW(u@^k3v8u_z96vY5T1`q}+*82BZV64np+Z)r zSvqqW^!K@PyR?w63X!fp6C5cuEikhu6F0xn@5?(*7#XP_6&KAr$^NULde`EtD`uXU zgv~vi*P_LX;yRlwE3H903>{jC{yRCjy2TcLeU`y*r**Di9XCSb;7Z6p#G)HTMm>5z zc7qW)jgfL34@Q-ElDDP(t%(0KgV_NdZ<=k^;*-^67Mq)*t8`Y~9m{$L%X93kMTE_m z)%AA$TZi9-6D7NK9YPAYhdR@~J#hllvxx|G%yV%el3UUrupGJBDyjkhT%PmCNkIcOH$Lz7l5$EYq1=i$1GAjm91B`qH3;n znOnf8%BhvSo!)EmvG|FrCI+@gNTVoHM1bz=Bt~5dY+&9#tpuD>Lvu(_sr!>ec^k$c}}K|a3Qv> zbo}KR>dZbQ7Ct7f)!C+u_qY?;Vh0yBW4Fc*ZOAWs>@47_PWJSyj{Rp+iN7%P$jA%&7#5W(npGH;*Wk?cGAgTL zGNsP9XY^7Ibud}Ff8S_~K#TFcs`k~@g-A*WE4?3IGtX39N@|gHYN=D%iaftS$DBEv zJ(LwOm$xoUJ^gd8ffC`E-RgbAccChXE1JmZ*DOaLhbip7XKaj5WMR|%l19WC_szs2 zh&dxLnseqF-4`1lX9fX$@Qc^AYDVFVyG1&I zEyneV@svAl_Bhht29enCWcf@>t(-P6+H77ZPrq5EI{cnooW(Ky;x=bTWp$pC z7vp->(oG|S{$|XGqnqpOl~qNF|pluI94P@i$^p z5jEd!q_F&l%9(mbbB7+c?#I*J3_$G$Sh2Eu_vT<+LnxzBOvW3 z+(2yWpT*Om!2J4o{Q$?KDV=+LEK{$1Y6CO9bsXs@qbO{j&314F#*}f7Fzs_4Wervq zd0p-u4pQOU(;E}g(afb$A{y z9~dg~%{6!-M=BF>UB8aMd*R=-)&@w!*Eh}IATFU?jpF*&ZyQ$dkWN!%9GiXgcz!Eg z8%;BX$1B^8$+H?3nIe4%_K?lDZlgRhzq)3e7&81~>~|@UyAxG;PJ3H|FS!C$Xr%|^ zbxTG&C%$_LKMq~AyhZ--4k2rh2Du1#Z@v50!i153hFk>cFM!J|5J+6cL{o`$aC39R zS03`OQ^CC-YHX5jX%H)C9q1$j8XN`ub>{TLGFx7;1(ph^U6Vtcg1UPwKiCkqbqQ4&4d~^8p`OsZOjeKK(i{VylTqDiy|qu~WY!h(*7+m*ZFLHT-MR)9TF`=PL+5CL2kcE_ zb13)lzq!vUeirfLE#-blKqCC3tUJD*l1iBmefVga84jfS9bvr7 zLGPJ~h^Vt|hB;Uto$u{FM9rhOyar)Ij~@e>OAi3_KHnY3M6pr}ToXlY$DjKFL%bTR z;T$x$Vp!+OV$|q8Rv!?RnlqlwqJF&vDc*rj>7`n0lfjWM9t$3aw?Xc>%aF;GR^YTv z`ZdQ+HJSo-)$|mH*?CRq^|g{e+}&uC@X;AZ2;$H%-@wnNIx{+tDB=gZo*JI}QZ2F`_< zMt*0(#oA>94D#`R017|B)tkg&umHevr`V^jP624T8i+;UEjV- zrJ8Wh;nFkItAjB}-IGSKZ6OBtbQ6SA?vi|>*8F~LI-R&>q0dsll5ygd&&}5OK#$In04@x_MoyR=S&lu{kV~`I^H1rCk7sQ^KV$j zAT#^MrWj{V)ppqOI4=ZNwhmwP@e;wfA|yYd>rLF3Js9>!g38Yg8-9ParUqu4!&XBB z)pLHmU{3K!ivUcXqReSXRrQ$Mij%v#XKBN48wZvs=9Y=#@ z_?etL9y1|c4o2ba4eCie^oikTS!qK*zF;dTB(!+UIAJNL2}E)NtIYSOS^n4E?0N`3 z@+Y6Wj}s&5S#1!yp?BnS<1;nL7p0Y%8}s-w3cYRN>o$!AEQ)SJck{WG&c%X5e1NNw zf;ffEi?QQhxYAk-dp-WOwL7P|O!h@zarw&Moh~S=2oUaG&F@6vYH(O_59P}z$eY6$ zc;&!A;$k#f4L^O1>0PQD{Y@S(VOzsy;T3y=uuvhrdaOvYaGaK0K2*M!xhY8+JYBD( z0v2(t(l1dNzYf+iZl}2)MI!b+1-OTQV5t?x2)B>jFDH#*sPuQ&yOWk#WG3VzRw}|O zKY#--d8??x*5MZh1t9@}@$djdr({-DW1;qtDa-)X*^iGw%kYTDG9dY%f*RVB_u_b~I#glCCE(7z z8c<}D6|EF>#dW31FTQS1wPMP~$3)lVL`k*+oM zNMbP&R3?0ffCIJkSNa6aVlAg1rtLMR?Vs;Q0B^~I7kUW08JHA?VY6T3#Mv6TRhY%) z;2=ddGProg0VF|80z;1;Q(@5KNdY$YO%d=14Sr|!dc<;G(w_Gg^#FmtQjuhb>=vp% z>EdY9@=*K~ZR8Bhdm|hgX*~bj9!L``;_?(Qq9RvyWzk zrS}BmQV|l}$3$mFqMaalB(*Ad-d(j<_4=s|JU>@96C)*U;T zFZYC2%yUY;YKP?v5f8@K)+FATQ?tfx<5qdg)gZHF(VW2hQkoYU8v=XBHI#({*%81* zh9v7L1R2P!*s`Ca(XMXU5elo&2l_>6br03HUF0p3#kYSQ8galC$R5t#mddt+Ni>oG zcrO6|djNubHU>xxP|jDAvP~Uo^?Cxhu6Ie-RFuAF`e07&J+)LH#(?k(@TQ3#C45)O^-6`M=PC+Tzd&bLI8TMUILs^ zxkgl$HVN{ta2L-+-9h{>gaOD`#5+zLAj#L)RXRpnUYXRBX@H!Mxn`Oy=8 zoe~-Q{Nlgmi*YYMD|CeCwCT$7TGV&NFGeWky9v`E+aY_h9Z+A@q-u@GfUOny7cJUXlidTgJ*jG!eXtq%@8&Gn1Tbt_ctM z{yvEh6pM_(vXhVogU1P(eO(&HpLCwcPvq!DE<`YmbK>*$ahlM;He0@?qrX*rhs9y4p z%PmPg($ytj)_P2MTzhju^aJB}T3o^SC1KB9T1xy|QfN5#!$p^{9ot`Z)Q_^wbP#Vxh_5tj7d?5PMPCRO$gk2e}@&o|Ov@}n5g zC5l8)gRqYdXfo!7aT^j*EeO6!3-dE)M4kgVEIH4WD&C|pY*%n(Q~F)w-z-C#;L}!q zqD<$bm%hq!!1x+fp7?OtL_3I#@Kw8$!%Fj>ThT~`_U!12Lb zSNVhM8XZkFYy9gc8V&mp1fvIHm*nxwIBP|hrHBxiB+JyXWL>Q=QtViFO@-j#pQ6hf z#k=l#UmoFBb|p&G%|}C`n|ltG{9W(kO9k)@?@#I{tX~rdxsK>da}8zN!b)Z@T3IyH zQaCy=UKsiN>M+|;kXq41fEDhHTd8g(_u~rUh;O0G^Rt6BA<`EB#|)?W^g0*poETKh7?H9;Cgyo~kFNxf zRfnI#Luif2i46NX4lU&1U*6lxVus*<3~;BOu)(VoRNoLa;x%mRd8gcqn;77(DZo4Z zGwo!*QoJ;AwIm%{{Q|c#nkl*Z#snr)D4=__bwP*R^@2?Iw7!&y8Pi>(C`>7GY~#NN z0`iA|V{^ii(r`_eO?xsRitR=4n0+ZJjpihHbj?8$iG9U4lnu=>ff=v}h=0rNWCB}4 zhag7;<0wQXMi9gIIgNU3U=3W7YlzV|fU}p|%=3!78j4#tX`+Qlm|PG1Ar9>?=UhB> zX~?s}*xIhT1@bI;a|7iv+uWLv*LL=uA$q)-O`-^7vEHoTNh^9xSlFeGqyiO zDWn`HnVuKps23+dXpYBaZ-?Cfs6Qb+C*L~iPDb6AO`BrIyHO0}nK67r0lHC~Pn@sG z*CfgQNRq8dmPSid^#;rUl;1>BV^pJx*OvLJ*mY9t@z$Fp^*{IYwodsrZs#UX$v#1F zv)lH%GK6opkV3)lQ&^oH>VF-`AWar${!jb5^(Q9^eRX~|*4)^d`75>rlw)p%*&yKaztsyHaWRcchM(IyJDHT(UtI=MrA(cOK zn5iS^dd|HuA*NRn1etxg2Ri|~G)?fa3RBmT#Oa8Kh%Z=EStd|K;27vg04f{^%XuNk z`adt_5f6I@2##Jt-So>o+f9qB<{YN~$k>6*>!m9QapQn=r z#w8W`?$+`ESSk~EpqqV0}_+^MPzkafq${wz4O$i!t) z14<3QBr#$>0yKHX=o_28*?BD;IkEH*`{$k7gLkU%RmR@~aYFi>Xuw#F7LHf>gnMBf|fnb)DvX? zR1C0j`OHfgg}2xPqf@bnS2e42!D&tZ-8*8p*c1@Wp`cM02ETvx~c!;?3M*6x574%)ct9k!4XEv~KS;ks5}1U{ls z;g^BWDOHRe?_@NapBIxuzz%{ZbsO(Uk{JJ%^nFq*=I_8ew7;GMdS22rp!MM$KC>F$ z;oRD55VJv@6C_0UI$siaKQ7#Yb;XMkQM0%4*%GP4dj(tqU1-oBVF06e?=51~U5tb$ zqraah4JYKm=jU$7;^>I5rxWF9evl@*7!0wqJ! zHf&VMwsxfAvD;#cw%o=}RC6PDJj(9!sTFzZ!)9=d7hWuQgtXozd?ArFn`=4*gqQ4a#3Y6}( zGK2(p`MB+Mg&E>%F@?YV;P)RVk58D9^R`2yOr1)=zH=L!9z0}T{i!nL;GvNcct86T zWb&sW$;%k+@t=w!jnezWmZJsRa<`bWOz15-+XpAV}ybI{W{ zNt)*^8r~$OoH6%xYPIoHFzYD(TMH9lLB))`&0kH(JjlsMkkgIg+?$i^aQT*AInPa+FNpIGyGs=3;2z%kZ&^APg+qw*r{s?kHoS-VWZ6!i zmD;m3E2gX=Ahv0|8M0ti+%bbGuZ)Q~L2IG}4PughuQ-CD(#GVrr59kk-1+}}-MU6K zgtJ{`*2_r@T3?BF+v>-UFk94h9bRRCoa-s_rIAAK=#CgFhHKTjKzq;AIP`BFSY&P} zcZtnHTvz4)?g$-XqWVec0Rup>vV{8yIL(HA{t@h)-qY`zM~aN+t`iV$<=5M&vkLvr z-6?BoHJZLpWIJy-ru`qe=d~HIv0#=vXM;44%B-@gn0Lzb%1I|QIrbdJjclwy5)eY9 zD?(U-M4`4AON^r!IzqRw!J$2SsW@1vk0k&XuL1W|U>=u>~*9ZYhZhi|l^C?I0- zVd7a&z!%mMx1{!EZQ%V0DSi%Jl}+NvJSJ4z>rUY-N96<(3>k1!x3IaS1c#iQoP3Tp zG{v13?(WPr&kZ&CUPLs@MN!V*Twg@z=H@y^`|mBhnyqtVD>H0N^#?syK-VPF&W?^$ zLuy>t6vPgWdRVO2H{D^-1lL zt-$-1guQ-*akZM|zhC3DSOXZwGYES<2P8Z)8=p#eS7fK56%Y=&I#8gG4Yy%9F?)?} zm5qLZ64mx}HK+gOUT4S;0SsK%pyV}BJFqjpCl#|vNO1PeuKjTKYH!YnrsFWaj#&JN z2U(NkR=v=*0ix|KY*O&3YVR+*nX=xc@K^}>Utfm2aF{G-5OkbP*Q>H=cWgW&23?B6 z0OP(LaG_T~_aY~Nfu3f*-{$VyX&Qf%P_F=a5Ik-OGfO#1Wulo!fJ0J??S~0s2aD7V__6lVJ_Qa#YqqA0Jw(( zxPy=*(E7?Tn*K&Pl`ky(30nte!|q3u^sNTKM^ERs)yiGbm6mGA#&fl2&}Ikz$+#R# zZ>V}=m9FMiuTCi>z$SP`Bj?M2fgFAcp*b>@e~&j&{eevw`-Dan4M()1%bRymk~=fC zann_{mZKaB%ppPcd^V$>01Vg(kW1c<7yj3x64$4T`b8QnhTn~E8-W_j@gcyqs~&c! zf^JlX70}3u<#vj-aLPGyF%@Zc#d6a1akd4=%dcS}u%AIbK6CMf`*UAuu~P%^ml`{p zqP=qg%Yu+@4b%JT{0QA?%xxhqdw;ptr9YMbh41+x8ppg|Npp<&MoBLh#kY_LCRP_1 z$r`aM@Tth()@O<~-y0u3;n!wos#klEkB~3H`08k1Hu5g;wQymY_q+^Pf)?aLS?ivL ze9wbml0iOpoSla&DsW|QUf-F(!j&C?ijd8yn|b0JX4K=K@0BTl$uGR2Ppumt#<&~(#JPKNdF>;x17 zeP1mSBPb@yjGD!axcl!tAYK~DSD1^6JhuBE+Yu`vgbnWj%f@kQ&4ml(4a!YY)E zoEQ;WzPeU z^3jzeaqq*gboJbcPJ(v7jYlEi(pg6DxA>_=J->qtb4+rzH)&8B@6a3&0KnPl=}-&a z)5*xg7%#|s1$y*#t$~CE!!9S#>1I6|tZ}eoDc~KVg(-kZzXW>hkpbOjM7xlJB}-IQ z&qq>Q>$k~b@7<~SZQ>ucr~=i)OYR{f-=l{xeVvjD#8D6MoqPixnZjgNI!15A z;H~Y4krJ4U*dKk=()&dnIR{6VLb>o&!`)SfA13wvKm|0M(1O|UNni+w2$ub?&qAy1 zr=dZPpS%)h?*gfcC8^07Y9NYA3T7v9+#-vhJuw-uo(f~$go zQ5}Ng!DLZRMg49SeWMd8`!p6k9_cKL3}Vkwn(*`jd+YNVvh8=)LScaV29iVf;3ZGP zDx0yb%zOFnIw2Y2zEf+G`R3hUW}1B8&o+4R`tP-q$TqDOX%>@1MHm@7UI#GoPx0ut zhyr#pfO*^J@{n^wWf?cUApk5l&%bT*4ZM;Pb6e51Zdk|NA*;GH?Mmd$fKIfjXxhFg zQ*z>LJ~bvQ&(V8r0^4#e0=8;YKZc}`g*JLOdqrj?RkxZ*jmZ$DW0Snocwz|J=ha8b z1{_aWa*uUJ(+H|fzNwK-VAZSvP1IzggV7Z!(2kL`YVeWB79Id`i656-&o-v7&vK@K zv~E!vd;eLz)AgaD?*QNRaG+Pz*o&Ne?V$^CJ`;h2?q1he>utj6Qz!hz>AnrXx=5_D z)ScG%5HwulLRNMjp4>h-;u}#|Xvu^W>+z0F{T%h;M)n{eWum34SzWK$Tr$>K)xn-a zQo+?Itd_JotDI7rXIa!ZTj=w{o2(*~S96w<@dO;xZ%Id@!=Uf=W?AzoDA6p#71NwS z>%v;C5?$H;gP{A5JwaHi?nE{DiU2ZxoNQ!OUR|7Q2 ztVHp_fgJ~&MVa^L8aP1>iNbZFc~D1@)CD8NjhS=Ixd!fn>bY)^w9(eRT04kWbbW2< z^vc|o8JxKIuw0?gI<)Cm{Lb42w^-fvoARO~>ut66r z#Q$QeTGmW5EG`jWgVHu3pHUZ3@`*e_DRYI!|1$Pu8)eJK8c%A=3oy3|!~_a2-uF`+ zt{Q!gK+j9ZuM{*Rw-4^pnFp@N^OW3dw)0(>!1b9PcaU0&502hY!8@UAOEykC6p!=XOc4oQjU-r0YmUKU-sj<_*gV@Bp8Qy9g2 zoc&lSxkbYdyXBuYa%8Ji5lYG?JNjo32%LkhP;2&2Q$gzr%ppjhL&#`IYO zSn+6LJ>&8t=CNFkMyMjk-`QMKOh9|l`qlmNM!pr&7`N`22 zHT5ApKh-05*4J4l3XE#-ub}Cvu_5&P0%DxhVt0n$5*W zwtHCW4i;VEnHDysxDM(^jbmjtDF5MJcI)?qT^tix60T>DEEJp%esWgLT!gP1D$RMv zSeq%rQ`0nRO+`hYJ+l;6M^8{ZQ1qK=*CSu?K`B++D61f!XFu+BErXioDB2&8D$U%P ztJU<22q$OYEpLoUbemL5S@)EJ_mUasz~U`asU#%$%~?zP4pO1uSilyiXV^(JJ;-@~ ztj3H$y-9tq6^GgE+}C!Xsh*Z(?Er@a7AG%vG{+ZO^An4`_Gi;Ked9~6X-9b-cb9;% zC$&GnGDYq*u9-DKbk6veSBNV=lMG4vMR&Xls25+nv-;@)rDE^BqOt`GzKA*M(v>4e zVUBnDcsEQ~B)>BvAMmLy9%=T@#$`PC+tq!~z0m2{e5{vBIG}J17ji7HVK6~zO z$6sM1%Tc%dZ#*{=d{CQ1dO)U2Rw6R?-tmL;2|hBM<1tVnAdpLz|BL)`v!x^6U^plA z;Ry~pDz zHYOGJNkDq1VZ`L0eO^tsB$^r|ukWO;*UUwZr5I8c^h3iiAcdo6U#6hPIiPunFn!aW zQC(Vk-9BTcQ8DJuKvKAenpeK_xnogzLj}ZURwvxka<~sM7q6BypV7{{KQQAJxzqXe zkNv9mr_cMEJzwJ!JfQ3yBE7}dy+vN;&wo`j^BS>yZPL~(f@vV(cEO&Ovoqc=_^I-m zb~s`Jjk1%*FfMK2tsB{}?XqnO8F<)uA*cFuDbtrJrP-n|sR7@Qh5N*ACBF+1or=>( zjJl4Y0gk*|?5&j*>E3J11tRY@>beR8^5V>?oipMsNDl(R@_7Ujlgo$zM9L;~j@v?F zQ)7A&Nd7+y_+33KK zbN)TP#szZRhJc zAZ&Vtp{EA7Z79%fDZip|lp+0T^1rw#y@$Ks+W1>fnmZ2>bzWt5t*$U;^)W?A^Tem- zJq7k-xyIzuqO{Qk4#+g?+B_g8DZbaYj!^PiRy8|}?7h|*3SA$xSu?-)8FKLVG*;Hh z49X?OH*pN_ns4YU8baH2h!-L213M|(XMEQl)`!dlYYuZc?Q6R+ z+{k3vrlRB4v0JE6G`7JHQomb0#5vsZsJ1Nc$!^JFil2X~lkrK$1TQiyTp=r;UO?nN zbJbqVJUw1F8x;R@O7-z6d&k*k{g});E!+c(=ji%perTUufu~C0579N51*{}yU&)4J zjvfAvSlZQc`@E=2>b|BdGF2-6ka>jHDeNswv2A^!lhJu zUN`69UI-jZ)Pp{>x3V!o{@zAz4fw>ue(jZI@k+%En7Sd6slfTLZ2M5sCLHB!N@b|? zKCW1M1{Co5`}eQZwBVe=+)qUQsPy`LDeNGIS32n@AepV2M(st!YERYHJB8Y2E&WOyoJ&X%7#mL! zf9?^y?SmJL-ZlP{2{9W~5XxgADc-i1Z#sC`^ABe<4YB`W7|=oZZ;(>0Ho(f1I2kh7 zDOrkIMRA{)38&6g6-GIoKB&0&D#xoSMV{uynL52YJNg8bPv!l)!upRiyyU1x`WJsg z82N!)&(Dc?2i4S1W!CsFyFy9-+9K?sNp`JIMl&A7Uu3SEJ5??7avj~gRsN!bGQ*)9 zj=bmCDO2H4Z=ydJzc=9BO{}z-!!z&Rk5J!opI3)ij0LJ*1N~qHS_tw_z5w{b3fIG_ z@=Wp17=|r4>o8l>Myrs{GO?wuk@!S*f^l}McKjj;2lxEk!0D+nTc@aH^^m7{NVl}V zCgg%@wsE&x@4Yhp+Od2H$&j#QEgT5%R$em^jE}v@O^mG<(%i68lHpE={=QRM8RzMe z{S@)CpJn?;=ZZjPWm+8U0MnQY zhff2Dw`GRW>r-fWso&#va^Z++^O9}r?+I2_14}=ezi#7rs*jycOb=tDK0IZ1m7yk# z%)A=)+U@!l(Mr(SB0cK|xO1nDmnmYwE2f<8>j+UXg%&Fe};gMQvyg zSB92s^{M~gI;=KQk`&}l9 zvNgK@Fl9@CDbwXMB``9JZN8fOzB<#UvKAC9lw#ApICZ3e!dO`8DU}h8xgo<@mHoI{ z!GaVGv~KZ)d;9Z>9cOZjw(>6|bv$mqrraAY3X^$g>=S4t;#+rT@9%8w+0nPaQ#bFR z-eLU5CLe#Cd-E^w!%0T33c{8K=CXG*Yh}5_a;X!0j@9N?nHAk?l*KITvoy6Zy>I=8 z623tcc(JX&G*M}-W7IPYmLHE64B_oZ*givE-mW{wPZ5H>vwdDuOoW{2OfgI!IQ*Li znRwu|C|9@F?r>c{wkj+63P zCUsgd*1wskw>2?`EC}ZxFzZ3FU-;n3ZoiDa>M={g{1nKTtE@(+Sx*6(lYZXkM9O~V5`i8qFX8TFc zUd85&s5*yVf80>OL#)b_MreU1&r_&^9MM~7ahD0rJ8 zO0n4K$7h7W_uuoJHrez{ZS(_Dh%4PCF7-*Vx|1p)X#_s=A(3sdTU2+~s14OBCwyd|WHk7}2n#$1ln=DD3Et2= zYr=YiVe7RkM-2{Xnb-nD8`94v(`L6iD}l+J$53IslahyKb&!%rFiSYk6dC8Q4 z>`o5m^>lBvq8X@0uQ>-@c?4~;vI+SI+SVOeGkROrH?IfEhH%9p`DeJxvKzJ7pHqk* zH%55B+kToRbaf0IVgGEVXF53B)Dl?KZD=6>&U~i=`K${1>0cROpmv$y?sIFdR?fFs zK?9%0ixivd0X{o?WQVYDS|F*7LictYD<9odzhf-r7ZWHYr_{P$GV$p%#bR zDNc_sXJoqFTX0aZ*(_D!wTGGLppHy()8AXblO&U}E~)v1ci}5tTd`htTwJ_9uWt_i z-eU|lUW-aR@)Jy?+=lS@qFLz0BlMMJajaf`g<$Kf}moK&qE%bf5|ODi!Rb*7bSPLUf`_{AKr_JcIZAKipI_U(U* z_i(778x=o&+1%<={Rb-%DHj~gRP~}E)`8Me)e>G~{A=9Xhc*neYIq@JBNsQKPgZ~M zMbZ@LT%NAA=wC+&Ybj}%lJAqLPo?35)k#1T_MGxIw}ee#-4}@ioTZxWjsr_EsSnZF zui0XH$*p1!&8y)I$U(*ACWlT9uZkvSw~L_lBw0un3KSxO!gbe3QQvd>o#C@I+?uGi z(#K0!MQ|PKpO--T{bMoLIi_o$NZ;CYt7@2x~0REcX+oVh2;=ty{C z%6M~YFrgM-nmOe8Cg@uw?9F?6rp(jt2}xkbLSm>Q_Jxx=5qRTc(PcVO$F!t^%y(^4 zm*ZCNI@Kr0?+}C52;wUSqeMDQM z>DG=@p^{<=i|;%olTKohSQu2&ovNT=v)`!scq8HL5ckl?WXR#=GfbW%Jo^xJkxJ*p zn|#%5TtR2oIxfT`nk&$gLWGq&5=Ub&7{OuGyKT(cY(Q~<#vxW@r3wZ&PL<0>tX90xQ4h)+w%ij#m~iFg{>zxn|@!u`K&jFZ04z}RT6e*LwSLF?cBqcRz*k5}}InY}Aw@$)aK#mXL}jPc;C zFH>qyscKEAST^OjihrofF*|infZFWxB7t$#epHPbU87-o&C0+s6EPzmjsbwBM6T(s zOQ`quKDKq@JT&V0C}i2?9qIb5E{v++qtDX>wQP+Uei5g#Y<icqk9EkD#>1@4$<{5SjdVjAie?9Xl5MC=~V^=_C zl2o#_>;O78%9=qv;|jtVU9s%zKE})?TfD^sA4a;)*l)){WL7qI)E=-eDm>p)Fas@F z_vzzh*b5Fh;J0_U+yEc%BybiG(Q*|>PtOm+f~7*9YB=4GK2kCwY?h!k(ZWlXWR8)o zt5%Di?*?2%e*dVs{wfGjlGmyU$WgMNFq?VU?F(AjdGwEYi-TKz z7#?)hrgNnd65)RtY%hoKW-egCiI;zr5juVg=0JdouX4yhgozt}rpRMEx5frCmEz4s z1)WRoq0Al!XqqQmc=euC5XIV?9?1z8WYHExa{;TFw&{jx;p4G)u7oa6)wPVE5F{pm ze(II>uuXbluKkbB7s=in<~@G1gAtVfuf4B~imL1TM(2`HQdAnGC51tT4nfHw1O#b` zp*y5Y5K!qxTA0BRX^;l#4(Uc@=$7th<8{C5{qTNz*LptQ^I_Imv*zrx_da|7&wro& z3#;TR6&{~~5X3)6A&Gq&Hu|!Pf+400f*PsUM9R~3(P62SP8ymNo&wJv4V3yxR6F@w zsjP&FFP42xW%-0dOQ(A7&fEnhX~(OHcT=c_g{A9P;+lQB(qQAmnpRor{s5|KMPdWl zbInsL~)O?v)Twj%~kbGTd?P$ip z^F|qBrNc|7UEcn2`|vRi8TQ1e98WVd4QtwFYOlYDIaU>NXc-{{0F*;tjilq{8$PjJ zVn@W;631cMgf8y?#vdE;n__ny9n=-_n)RvWvF8v^i#&ERBR7AqHu z4@MPHS{M?T7KNc3*6%6s52PpDVNAP8u_(^6!!7gkStjFiWKQ44s?SQ6$5&lW zNq5!g;yFtznsWvVMJQ7z7!e(ftA$$*#wzc9jG$97E^1iGQO8W=cDpO3tdQeC!uy^+ zeB}NCbsR?dy`NM))X+Vlvc*vQWGc+<58d$F!WRZX){-|y9EpzDYDOoA)zJMrnEocC zHq5Cpwozv6oMa7j@Zmdhi}wKq_VlP8AwpX&{)MX-boI-#2Jkud=VFa<>j~0ad?Lt_ zg_b3uDG!uD$ja1CwG2F8i#L9}fB&f=3bAQpME8Al8wl9z=%9ofR=0_IH9Z5_0---= zM(lkgUIWAzR9jM2Ey(&y|Hppft3smPpHeNk&ZK@`6~erH45ip{V2BejIpdd6FfK(V z@84sH1~}xzwl`VSP4kvh)jG6t^kC=0VOUe-{468{y)|~m`iFPNm z>d$^wXJYDCC$zs)OkCxH_gMrFM{WSi_{sAcBKuU?<6 zOix>(=N8T-gp6E9d@Y;kbZKX%w#VcNBh!qEM(kIIoeU^*LmHsiG*ObO{#Gd|KC;t$ zeqB+V48EI2NeBQ%)MB(nYEEW|4iqGqyV7_khfK`%z^z+FQ+R)Ab}!iK_iiy_L2SRm zCSPoeKh-nQG3TCgzcDl~lB84MM#{HIzD=E5(|rkeVDD_-i`dJ%#iMH}(|12hZ&|Vi zin-wqC5yr(1c3Ng;3`o{&PTfz8EI8xj}@ToP}m~UorR)!8=$O^O(4m117f>-^9>{E zuAeq^$KJKn0o?#~-fEk3vJ-A!EloG=DvUdju=QUo{Q2{P^!M-$^W;H2mDII@76X(- z9xs8fx{`DAJ3Ot^9IBzO3Gh}zzC}^>rA5{>G3VNJvgbxOiBTLhJepIQ%j0*ks z>=NCsgS1^=ADRu`_An5WTNp}I zH9XC{?+IK0SRHJ~rginZT;0^ocXnw~jq(Ugy6oxt3Sceap6h zJoZSKZXUKnD#wS6TRdX!dae?Ha3gtamz>go+VYP5@KA#>In4QKilZmd6jLju1?E0> z^lbomee586o3vqHbT@}Wfi(1^@^;(31J0q1T#y^u-B}HFt&W_7Qy0+BDQ*HUWyPrg z+B*jhoh!SN_du?yGdS+BWC8~!C5u9>`$4DT=SnEvA(zy$>|)6!0AMotWPjhxbMZOt zj?2sR{W4*k4Cc#Pjvl8+<0Vuw7s&EE&s9~Z29~lt-fJ=b0NP?#Vg*jiyU>| zjhDbfnn)!dRpXWXY3ugTzHE7wpjzl^T|N8?@x1rRz1gJ`DHy8%jL!#{0Ynpha-4g& zMxCPb7AGg-ceVx*N{GT$866z!7%ZiA=K-fbN^lQlK_$xddjd3@_pt9KI@FekBt4jE)^KJVvSv&oyl?Kg zYY7$&=E8YB?R~eqRLS5;5VGPy)h}$5N=kd3Z}pHXYOaK~{7(Ygsy7{O&RB2dH@9(6ld*)Lu=X``e zkL0yQ_YPkuqBaDQKAd;Qt>>tVuf8JN9dg9;i^Zp#c+7(gA7$H{-R{2L36nr1A5J%F znAa(Xux5Nrj-&5HQqeKgLT<-9;7_sk%e(rXuRlDfTM8bo&3;YjO1r4G?8aUHG}-7A z2_*a)d{Kf0NyE>gk^Ojg`-^04o+_b%T%eE%nhWm50d;+0<_3r{Gxw9k*P7!ltECs3 zla6QakWyHNV81_XmGi8LJ#pQB2SA?jbI6c>x=gOF&js+!L>`*nT%{*)8jO8@vDlen zShIApPbJ6mny6EZh)iusxUdBK%3e!BU5pqbjd2QC)L%35&%s7$Jw}ydQNGjmi@h3) zLHddEWwoX9C5xe$fe!K?B5kxy%bZfOLMm`3W*RCXgmYaMI3*Bdkhb zS$*%~)2Xhbvs{v#e+ zyDpbv&Rnmv8(V)2V14d^m8WzqfwP+Jn3_p)!%jI-rHh#t>Fz%IV&|=nLBYPnn5-p_ zl=o-D8YxWO@>ixn27h&=duJV||gxaH{(yj2AnFW9HCL9RY(?U||(6MOnVT}Df7sWuBb zhtthN!uhv^d3lffUy!b|)MlfVKJp5!ra$Bx)tB-co zV}~7MUaY&&(m3%t$DO7p94BlZS0_A8qf3^fGekpoMqDgUgb~req?%F85&pG>g(8bQ zn#RoEmc)IA$1$VYRNW1k4)`UOsMne5)Fc)0ENl>ct<7_b+W=LVPF4l~`;%r8bWJR5tvMAS;Gv&@^?VBhm z>susJvdXLmtEEyE58hYSH|EIYu6oIJ8Vns-PFC2&Xdo-7n$;3j{S-G|pPt*HPU?hS zF292>L!G`-tv$O>klwt%Q+B*>rlro7ou+eT#utyaLmLSk*rV+_0Eb&}%Z1DLe5$!1 z77*IF_ZpPn=hj(L`SyPIZa>jGvhfW+*dLS3TSPsWfw!Uyzcy&;$>n>kDJmS*x1$ZW z+tG<{mV}uv+jSL9F?GztzHf44be2n4L=7%`RlIq#FTB{*?IpwRg@1SMohqi(bmEp~ zitAKi9`A3Qrj6KBrk|Qw5K3Tw`4+f|KMRSzHb9FBr@(jVV*FF$(33&uWVvx(@IIaY ziC^C>|B(J%FCCYK3YOZOGxE$VDZ z)+^av7m!xt6~le1GYo}JDYfdy9+aK$*6Q2rpY*hkP(`RO7^tNyC2uX$nonlLqK9sx zu;-v$md3-!un4;z`}W=?7xO)ynX8);4S#fLcSjWX`=A19L*o0;p+*~cpux|%=R-Kq z&93(0bLWeTNRg!3ZHqIXcb8Mg)+iWP|RI0|EmtP;B6~PL7UWRHt=x_G>;xn(fpeLd%$rXi{W%3IFNwH}gXH`Jxme57 zt9iv+p99Cr`>3KUuH~6)un@n`Eig-C&)8gF6jS<=_Y$MXG4_T(Z z3R|wVIrIHxonC6E-n43=gsh37vf4f?Xjn^vM&L~%e*V*ROSytpE zk=W@`q&sA@)8({;d$y;9LwbF^Y__em#BLT|G2*)a-R21cd=>k2F|q2+#i=*N8B9A_ z%V*6X8R@N0>ByfI0|cri$@tmZC5=HkLx+YZ6?O<2mE!OZ&wafNr$5FwA>`NR6=cjD8$(3`AbtBg)z; zetfvk@m2>r4_l{e=XAX=h4w1VZFat5*0WnJIk1jS{CuZ5Grrbr)x?Yb+h8R0LtCMz=360zxCVfN1@tla?qk!ReixkvsY4 zHCR(7Zdwa$vc=!C&jffW$7^k9%Ru^$TZO7wQs;#^v(Uz2w0hO6Vq@>qeM|L)ztXeu z?5#jk0IDAhRCIUqbu0chtc;wO13~`8f_My&zz2)xyL}(2qrz5A*v1i++x2IaFS2D4 zy3Tv}`u`~h-B1>n1+*nl?c2j>(hAF=w!aPYJlvodhL%~4e5i3*HAeSb<0pk(*Z#=| zC%8OHXiU6t=odRmqHTB@h&^3lZ>WekL`X0t1{@Caa1EfkW9eNlXA(VxeUHlEeBoDb zqj4s`(N|PQ)Z38#nos&rc2k>wz&Hle~O7zvtqkUWuj3>6utM+jGHd|UU$qWZwI2t zI1`D#Ia$sp=DR&xcQWg>U9Pe8dK-s#x{*^FXp?hM70c3k1OaUUiZbXc{(-Dl*oKGF z4Zauf$T@)iriIxgA)#j_bTKtxX^gs@ z?jdk(C{A@($}j~rTYowwb-5td`%5?QpWwTwc4I+kDgmL*SuXCz65nFn4N!|;5utno zgU8BEbUl>8%jsTyPRD^yWJvZr&W|0{7ZjTx^V%)Qm%Ef}aE=)eY?#DjDwzL8_&L5i$01NDP}1~yJP zzVY<8AVOTAG*eLC*8qe|5K2QeuBVI-$!3{2{Z(ZMzT4AH(_^zbvWq_I>sw zT0{IcFexl8DKfnOyeCog+MMK9U-+n^769v5mtA@YrPN%F|F~{H z1_=$L5g82?Dtr4F5p{g5%GTUWB+&yD2EJ>Ub#jwfA&Leo;gkvT8(;6g)ek0NlmTP4 z&hr3j#ge~+iB-}05GhO16aREJDG6!P9?>?1&+&>Y@QHBQB;idgVrqsy$wK{_(JwDz zdhVIDh3&HQMgzb-6vfL|FK5>WB;ldl1!iqzkXV?l&b8nOdKb9_15oWY4y95=N2*Zi zDiqA#uNr7$H2z{&`~sN1DcpsH2r%HJJL2ZA#mlFwoORhtYs2xDq4(I-g6`aV^cvmM z$SvI&!yKp+3?h&-z%+BkSJ_OIq%z79#?k*kM12!8YwwTeNQ@TiR7lQGc#2;!qTzw% z|BE=fO5t#Ot{+Tb82qz@hml)Vs7h%C$t;SAiq2 zmOFm8H$mVo7?CP>n~ab>^9I<4-PC=EC`SY(2SSD-rUAcXOS9X?H7((>A>r6f$x!0r z&PxoxkB!YYEp3{)L`xtZA@?YdrgSkp2pZ&+9QZOghtv5>Tw?|lu%okkz+J|fD7k@k z{V4+B`|kl3(1*naN0O>fj|Lw8j%e z;>C+LAx@eH@~|9$W;cS!5*z#LcXsV}7T3!cbH!MTNkTJ7$N%}k>69HuOV#=)ACO6a z#Iz050U7B==(NkV;{o7fAfs<945}~ori`s5{Q?Y;dY{;YRg`jC7m$b-P=m{VD1CeD z4&`e5;l@ND0qtA8N{0Y4&R0Kxh`oSXE22B0ciet3prx?k(h4oj5aqpGyus?RbFtSi z5x%E%m?63&Olh%dDvw|6QmIkv?#PHtSwZKfD>(RG?zYp(`2GfhDilJ;i-j(;dkt3? z{c6j~4@HZNacQnsc5vy{yvC#QjV+*Cet<>q#QmBSt5mPSHw~~tn&^Cwvy37ZKR;v} zyae~-p9T4^%&U0ZD(Rv!?YEpr6YiKu&ag zWal3>6Y;nqA3|Pmjg@DSAG8nJTmcH}v$ng2}zo^nLq$c1Xgk+JBdqNdJh^RUEMIqw$8hSq?ZQlr8`V{JxTXO?claxmewjtIW8i}Yu7!Ys zr&g>;9K{KVKM%|7=fvy1PfCjIk=-V%QKq}UTX7rk9Q!gP`X$bH0v*$@s~_3QaN`U#TSV1oWp0nWSb6z7G-o)kTHN+YX@4HAZpP!(WVspLJ8Qu(PhbAyJLAD02&{Sk9p$Ojt0#IIFl^eQvXHnm8t5I>yQ#uuN@t{4vGukIH_2dB~67RKP zHk*B1h8Srh z$6cyTo6PnI8ZQw$9ZI4uYZG+%n{UPUAY6NKyC{{62%5W6=V1P{P2I92uf8@sXy&-j9bh`s z?R)9r;Phl52A%D^+}GAzRvUjaI#7bYCaX5R(dr@Y|EcdY%Hz%P;^vML`iTb^{=yc; zE^9;C7RkmL$;X-YzWcN07w#;&h5OdLCk2ydRISOJM;L>_oxCcQR?aB-b%Iu70C<0w2wA{sDZ-x;y1 zfy7gr`(Pz;5Fzj#ff~;-U%oW9*zBOXBd_}i+p{H<1TO-Ic(Rgj;7>yf&(Zo=Bp}6k zdsUKKcvv%GUq4aIf=rz_bqHs4%wjAfgAHrVi(;qAOAnjjb`MHILDG7dX1W~*%VD#cSIU~Yx7lj{=MFbO2vA9cO&qq=;lM}A5ZXauY#{q1?^gH0`L-O7& z;S*EmE<5%swfOfQ3G)%xtzOf#%E)_}XBOl;E;1U$Ltu%1jMAp$?hMzps(kimCZYxC zq{mQ5!eO{HOjB)uO=9=tVeIVE#>9QhanYE9LVwUoG>^A~c_uSV2f8X(dseeu?{zk> zUEw}4q&5O{?ko>0EA;XLl*C?uZ{V!Eo?D~ALLMB8QRw>~|q5d$%J|2hWO zKLlxSQYsb62cv|sD$Btf-oepMd*iYk84)0WsI80H({ICxepgZS-a%W1 zFC0?G&;E?D>7MWP?KX^}?vMGcVDM8o#HvGSBK?E170Ppe#c2NxOE~u8%LZ~z-kuEK zQ#3F9&uzuTUxU95t#Xjr5AYZRNbZPX2m*6TVtqK$EPN`I*DV0|H0*+7dAIIp*4pJ81A+WvezYh#XodX;On59c5wyNVT#=RC z_;d6ij}xv;!BUQ%iq?XA%4|>Vg*FlK((*sB8#}k&>n4mI$K*}C3|jz$_yo|L`0&3E zJIHGidfW#@%c_6ENm^CA!$)Tov!?x#cZ}NI6^M1@vUzyB|75D?X>u*(zuniwDZS?_ z7n+dT9uui=6-yI6aL0o@0Z!#a+kL`DPjUDA{J7++Nu`b|F8geZdz9m1)&#FIEfy97 z;Cc{0VM>*D`e8R$Kf}|v6}6QK+>tDEYTh~$5@G1&njDzSW`w40hjKEZ^!rR!sh{_h zh+sAYsfmocnByRz2*6YRHxuLpbmG59{V{O{5KlO|$e{kRE;6MsL~mJ9zL-2v>O zzem@i>;L}rw=i7tXQq!dmTfaa;yq5Fpm6^VY&Qs2(`Jq<)FsPw<83*20DEq(hr2F- zfrIlzDyguD3s~)w$g3suO?U{(_ITVD{+3PbAb|ByPsM^6 z=*j-QY}U;!Y^q{0hWLY41%TuIt*~ysqs5<{*1?ge;pX)beeyxMoT8 z-x}fm^KWGzrUPTebQBR4oM#{MWN3442ls z1!v)P@wN}XS%R*9_Tb;b3KPRf(%TM3hIRB=mxKM&+je3375KEF*C~3G#^2)8$_xgZ zwUv&Rtc3ZRy?dADt@NdU;{#9bEi5czZSWT?p76)XkEI+hVm)<0pGMyTor0yFL_mgj z0M?@5KJAcAgW95ahHkwP{JSQ_@^AQio>FD7-EryVynz`wF8~L${qN_0e_UJ_`@c5G p{#)4f`tAR3V*amYwQlb#Lf=CHc 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 J^xty|^k3K<3BLdU diff --git a/docs/frames/category-menus.html b/docs/frames/category-menus.html deleted file mode 100755 index d952658b..00000000 --- a/docs/frames/category-menus.html +++ /dev/null @@ -1,490 +0,0 @@ - - - - - - - - Introduction - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/frames/closed.gif b/docs/frames/closed.gif deleted file mode 100755 index 69d0e9dd062df82e2a71e1408636fbea8d8fb3a9..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 827 zcmZ?wbhEHbWM^P!_|5fdc~z Uw~~*>goRG+?1FYW5&{g?0BhI;6951J diff --git a/docs/frames/favicon.ico b/docs/frames/favicon.ico deleted file mode 100755 index 731bf3511d03502d9f6905ea437853f7cc8d123a..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 318 zcmZQzU<5(|0RaXO&|qX>5ChRb3=&ZQVnzlQAj!aR08FA1K3+Zyf0mUn{JC|6;m^A# z41a!oVfgdy3&WO8TNvKFd&BVM-yeoQRVEC74lQB$v#E#S&$BBGZ@vM=KD}Z11C;xZ z1MG*0|JnqhwY|@S7@tM|>;Y0=PV4_ST>t<7Cz=2M|I9Xhyi*@2_)1W4F-Xn-ul^uX wQBZoLpwR#S2L(3@ZUoYIdn@{Xl>Gniz{bYL!0!M5dr3)2dHsI|pbIF$0FfD}?*IS* diff --git a/docs/frames/fortran.html b/docs/frames/fortran.html deleted file mode 100755 index e9166c49..00000000 --- a/docs/frames/fortran.html +++ /dev/null @@ -1,70 +0,0 @@ - - - - - - -

-

-

INTRODUCTION -

-

-

-

- The library is written is FORTRAN 77 so - it is very easy to CALL any subroutine from any FORTRAN code. -

-

-

-

-

-

INSTALLATION -

-

-

-

- See how to build section -
-

- -

-

-

USE OF THE LIBRARY -

-

-

-

- A call to the library is trivial. - Make sure anyway that the variables are of the same type as defined in the detailled - functions (subroutines). -

-

- To link any FORTRAN source code with the static library - you have to add at the end of the compilation command the option -Lpath - where path allows to locate the static library file and the option -loneradesp - (make sure the static lib name is liboneradesp.a)
-
- If you have been using the Makefile to build the library then you have to add the proper - option depending on the compiler in order to force the compiler to add only a single underscore - to any subroutine. e.g. with g77 the option is -fno-second-underscore. -
-

- - diff --git a/docs/frames/frames.html b/docs/frames/frames.html deleted file mode 100755 index 65d8c280..00000000 --- a/docs/frames/frames.html +++ /dev/null @@ -1,5615 +0,0 @@ - - - - - ONERA-DESP library - user's guide - - - - - -
-

Common Argument Definitions -

- - Throughout the library, numerous - input and output arguments retain the same meaning and - format. This section provides the definitions for those - arguments. The particular definitions given here are for the - functions that perform a particular calculation for multiple - points (ntime, up to NTIME_MAX, defined in - IRBEM_GET_NTIME_MAX()). For a few functions, there is also a - pitch-angle dimension given by Nipa, which is up to NALPHA_MAX = - 25. For functions that can compute for only a single point or - angle the NTIME_MAX argument can be ignored.
-

- ntime: long integer number of time in arrays - (max allowed is NTIME_MAX) -

-

- nipa: long integer number of pitch angles in arrays - (max allowed is NALPHA_MAX) -

- kext: long integer to select external magnetic - field -
-

-
- 0   = no external field -
- 1   = Mead & Fairfield [1975] (uses 0≤Kp≤9 - Valid for rGEO≤17. Re) -
- 2   = Tsyganenko short [1987] (uses 0≤Kp≤9 - Valid for rGEO≤30. Re) -
- 3   = Tsyganenko long [1987] (uses 0≤Kp≤9 - Valid for rGEO≤70. Re) -
- 4   = Tsyganenko [1989c] (uses 0≤Kp≤9 - Valid for rGEO≤70. Re) -
- 5   = Olson & Pfitzer quiet [1977] (default - Valid for rGEO≤15. Re) -
- 6   = Olson & Pfitzer dynamic [1988] (uses 5.≤dens≤50., 300.≤velo≤500., -100.≤Dst≤20. - Valid for rGEO≤60. Re) -
- 7   = Tsyganenko [1996] (uses -100.≤Dst (nT)≤20., 0.5≤Pdyn (nPa)≤10., - |ByIMF| (nT)≤10., |BzIMF| (nT)≤10. - Valid for rGEO≤40. Re) -
- 8   = Ostapenko & Maltsev [1997] (uses dst,Pdyn,BzIMF, Kp) -
- 9   = Tsyganenko [2001] (uses -50.≤Dst (nT)≤20., 0.5≤Pdyn (nPa)≤5., - |ByIMF| (nT)≤5., |BzIMF| (nT)≤5., 0.≤G1≤10., 0.≤G2≤10. - Valid for xGSM≥-15. Re) -
- 10 =Tsyganenko [2001] storm  (uses Dst, Pdyn, ByIMF, - BzIMF, G2, G3 - there is no upper or lower limit for those inputs - Valid for xGSM≥-15. Re) -
- 11 =Tsyganenko [2004] storm  (uses Dst, Pdyn, ByIMF, - BzIMF, W1, W2, W3, W4, W5, W6 - there is no upper or lower limit for those inputs - Valid for xGSM≥-15. Re) -
- 12 =Alexeev [2000] - also known as Paraboloid model - Submitted to ISO  (uses Dens, velo, Dst, BzIMF, AL) -
- 13 =Tsyganenko [2007] -
- 14 =Mead-Tsyganenko - onera model where the Tsyganenko 89 model is best fitted by a Mead model  (uses Kp) -
-
-
- Notes: -
    -
  1. - when the magnetic field - model inputs are outside the allowed range bad data values are returned. -
    2. -
  2. - When solar wind inputs - are required they must be taken in the vicinity of the day side magnetopause and not - at L1.
    -     -
    3. -
-
-

- -
- options: array(5) of long integer to set some control options on computed values
- -

-
-
    -
  1. - options(1st element):  0 - don't compute - L* or Φ ;  1 - compute L*; 2- compute Φ -
    -
    2. -
  2. - options(2nd element): 0 - initialize IGRF field - once per year (year.5);  n - n is the  frequency (in days) starting on January - 1st of each year (i.e. if options(2nd element)=15 then IGRF will be updated on the - following days of the year: 1, 15, 30, 45 ...)
    -
    3. -
  3. - options(3rd element): resolution to compute - L* (0 to 9) where 0 is the recomended value to ensure a good ratio precision/computation - time (i.e. an error of ~2% at L=6). The higher the value the better will be the precision, - the longer will be the computing time. Generally there is not much improvement for - values larger than 4. Note that this parameter defines the integration step (θ) - along the field line such as dθ=(π)/(720*[options(3rd element)+1])
    -
    4. -
  4. - options(4th element): resolution to compute - L* (0 to 9). The higher the value the better will be the precision, the longer will - be the computing time. It is recommended to use 0 (usually sufficient) unless L* is - not computed on a LEO orbit. For LEO orbit higher values are recommended. Note that - this parameter defines the integration step (φ) along the drift shell such as - dφ=(2π)/(25*[options(4th element)+1])
    -
    5. -
  5. - options(5th element): allows to select an internal - magnetic field model (default is set to IGRF) -
    6. -
-
-
    -
  • - 0 = IGRF -
    • -
  • - 1 = Eccentric tilted dipole -
    • -
  • - 2 = Jensen&Cain 1960 -
    • -
  • - 3 = GSFC 12/66 updated to 1970
    -
    • -
  • - 4 = User own magnetic field. The library then called a routine which has to be written by the user - myOwnMagField(xGEO,Bxint) where inputs are - xGEO a double array of 3 elements (x,y,z) containing geographic cartesian coordinates in Re and - outputs are Bxint a double array of 3 elements (Bx,By,Bz) containing magnetic field components in geographic cartesian coordinates in nT
    -
    • -
  • - 5 = Centered dipole -
    • -
-
-
-

- sysaxes, sysaxesIN, and sysaxesOUT: long integer to define which coordinate - system is provided in -
-

-
- - 0: GDZ (geodetic; altitude, latitude, East longitude) - km, deg., deg. -
Defined using a reference ellipsoid. Geodetic longitude is identical to GEO longitude. Both the altitude - and latitude depend on the ellipsoid used. IRBEM uses the WGS84 reference ellipsoid. -
- 1: GEO (geocentric geographic; Cartesian) - Re -
Earth-Centered and Earth-Fixed. X lies in the Earth's equatorial plane (zero latitude) and intersects the Prime - Meridian (zero longitude; Greenwich, UK). Z points to True North (roughly aligned with the instantaneous rotation axis). -
- 2: GSM (geocentric solar magnetospheric; Cartesian) - Re -
X points sunward from Earth's center. The X-Z plane is defined to contain Earth's dipole axis (positive North). -
- 3: GSE (geocentric solar ecliptic; Cartesian) - Re -
X points sunward from Earth's center. Y lies in the ecliptic plane of date, pointing in the anti-orbit direction. Z is parallel - to the ecliptic pole of date. -
- 4: SM (solar magnetic; Cartesian) - Re -
Z is aligned with the centered dipole axis of date (positive North), and Y is perpendicular to both the Sun-Earth line and - the dipole axis. X is therefore is not aligned with the Sun-Earth line and SM is a rotation about Y from GSM. -
- 5: GEI (geocentric equatorial inertial, of Date; Cartesian) - Re -
X points from Earth toward the equinox of date (first point of Aries; position of the Sun at the vernal equinox). Z is parallel to the instantaneous rotation axis of the Earth. -
- 6: MAG (geomagnetic; Cartesian) - Re -
Z is parallel to Earth's centered dipole axis (positive North). Y is the intersection between Earth's equator and the geographic meridian 90 degrees east of the meridan containing the dipole axis. -
- 7: SPH (GEO in spherical; radial distance, latitude, East longitude) - Re, deg., deg. -
Geoecentric geographic coordinates (GEO system) expressed in spherical instead of Cartesian. -
- 8: RLL (geodetic; radial distance, geodetic latitude, East longitude) - Re, deg., deg. -
A re-expression of geodetic (GDZ) coordinates using radial distance instead of altitude above the reference ellipsoid. Note that the latitude is still geodetic latitude and is therefore not interchangeable with SPH. -
- 9: HEE (Heliocentric Earth ecliptic; Cartesian) - Re -
Origin is solar center; X points towards the Earth, and Z is perpendicular to the plane of Earth's orbit (positive North). This system is fixed with respect to the Earth-Sun line. -
- 10: HAE (Heliocentric Aries ecliptic; Cartesian) - Re -
Origin is solar center. Z is perpendicular to the plane of Earth's orbit (positive North) and X points towards the equinox of date (first point of Aries). -
- 11: HEEQ (Heliocentric Earth equatorial; Cartesian) - Re -
Origin is solar center. Z is parallel to the Sun's rotation axis (positive North) and X points towards the intersection of the solar equator and solar central meridian as seen from Earth. -
- 12: TOD (True of Date; same as GEI) - Re -
This is the same as IRBEM's GEI and both are included for legacy support. TOD uses the "true" (not mean) equator of date and equinox of date to define the coordinate system. -
- 13: J2000 (GEI at J2000; Cartesian) - Re -
A key geocentric inertial frame. X is aligned with the mean equinox at J2000; Z is parallel to the mean rotation axis of the Earth at J2000 (that is, perpendicular to the mean equator of J2000). - The mean equinox of date and mean equator of date (at any epoch) correct only for precession, and not nutation. -
- 14: TEME (True Equator Mean Equinox; Cartesian) - Re -
- Notes: -
- Four geocentric equatorial inertial systems are in widespread use. These are J2000, MOD (Mean of Date), TOD, and TEME. - J2000 defines the axes using the equinox and pole at the J2000 epoch. Correcting for precession transforms to MOD (which is identical to J2000 at 2000-01-01T11:58:55.816 UTC), and then correcting for nutation tansforms to TOD (GEI). - IRBEM defines the geophysical systems (e.g., [GSE, GSM, SM]) relative to TOD, although some missions define these coordinate systems relative to a different inertial reference system - (usually MOD). -
- For details of the approximations used by IRBEM's coordinate transformations, including the equation for estimating the Sun vector, see Russell (1971) and - Hapgood (1992) -
- TEME is the inertial system used by the SGP4 orbit propagator. - -
-

-

-

- iyear, iyr or iyearsat: array(NTIME_MAX) of long integer year when - measurements are given. -
- idoy: array(NTIME_MAX) of long integer doy when - measurements are given -
- UT or secs: array(NTIME_MAX) of double, UT in seconds -
- Note: In matlab, year/doy/UT arguments are replaced by the single matlabd argument, which is a Matlab date numbers (a double precision day counter created with datenum). They can be generated, if needed, using the helper function [iyear,idoy,UT] = onera_desp_lib_matlabd2yds(matlabd). -

- x1: array(NTIME_MAX) of double, first coordinate - according to sysaxes. If sysaxes is 0 then altitude has to be in km otherwise use - dimensionless variables (in Re) -

-

- x2: array(NTIME_MAX) of double, second coordinate - according to sysaxes. If sysaxes is 0 then latitude has to be in degrees otherwise - use dimensionless variables (in Re) -

-

- x3: array(NTIME_MAX) of double, third coordinate - according to sysaxes. If sysaxes is 0 then longitude has to be in degrees otherwise - use dimensionless variables (in Re). -

-

- alpha: array(NALPHA_MAX) double, pitch-angle at input - location (in degres). -

-

- R0: double, radius, in Re, of the minimum allowed radial - distance along the drift orbit (use R0 < 1) for the drift loss cone. -

-

- maginput: array (25,NTIME_MAX) of double to specify - magnetic fields inputs such as: -
- -

-
    -
  1. - maginput(1st element,*) =Kp: value - of Kp as in OMNI2 files but has to be double instead of integer type. - (NOTE, consistent with OMNI2, this is Kp*10, and it is in the range 0 to 90) -
    2. -
  2. - maginput(2nd element,*) =Dst: Dst - index (nT) -
    3. -
  3. - maginput(3rd element,*) =dens: Solar - Wind density (cm-3) -
    4. -
  4. - maginput(4th element,*) =velo: Solar - Wind velocity (km/s) -
    5. -
  5. - maginput(5th element,*) =Pdyn: Solar - Wind dynamic pressure (nPa) -
    6. -
  6. - maginput(6th element,*) =ByIMF: GSM - y component of IMF mag. field (nT) -
    7. -
  7. - maginput(7th element,*) =BzIMF: GSM - z component of IMF mag. field (nT) -
    8. -
  8. - maginput(8th element,*) =G1:  - G1=< Vsw*(Bperp/40)2/(1+Bperp/40)*sin3(theta/2) > where - the <> mean an average over the previous 1 hour, Vsw is the solar wind speed, - Bperp is the transverse IMF component (GSM) and theta it's clock angle. -
    9. -
  9. - maginput(9th element,*) =G2: G2=< - a*Vsw*Bs > where the <> mean an average - over the previous 1 hour, Vsw is the solar wind speed, Bs=|IMF Bz| when IMF Bz < - 0 and Bs=0 when IMF Bz > 0, a=0.005. -
    10. -
  10. - maginput(10th element,*) =G3:  - G3=< Vsw*Dsw*Bs /2000.> -
    - where the <> mean an average over the previous - 1 hour, Vsw is the solar wind speed, Dsw is the solar wind density, Bs=|IMF Bz| when - IMF Bz < 0 and Bs=0 when IMF Bz > 0. -
    11. -
  11. - maginput(11th element,*) =W1 see definition in (JGR-A, - v.110(A3), 2005.) (PDF - 1.2MB) -
    12. -
  12. - maginput(12th element,*) =W2 see definition in (JGR-A, - v.110(A3), 2005.) (PDF - 1.2MB) -
    13. -
  13. - maginput(13th element,*) =W3 see definition in (JGR-A, - v.110(A3), 2005.) (PDF - 1.2MB) -
    14. -
  14. - maginput(14th element,*) =W4 see definition in (JGR-A, - v.110(A3), 2005.) (PDF - 1.2MB) -
    15. -
  15. - maginput(15th element,*) =W5 see definition in (JGR-A, - v.110(A3), 2005.) (PDF - 1.2MB) -
    16. -
  16. - maginput(16th element,*) =W6 see definition in (JGR-A, - v.110(A3), 2005.) (PDF - 1.2MB) -
    17. -
  17. - maginput(17th element,*) =AL the auroral index -
    -     -
    18. -
  18. - maginput(18th element,*) to maginput(25th - element,*): for future use -
    -     -
    19. -
-

- Lm: L McIlwain (array(NTIME_MAX,NALPHA_MAX) of double) -
- -

- IMPORTANT: When using a non dipole field Lm is - pitch-angle dependent because of the McIlwain L definition which has some limitation - but this dependency has nothing to do with shell-splitting!
- -

- - Lstar or Φ : L Roederer  or Φ=2π*Bo*/Lstar - [nT Re2] (array(NTIME_MAX,NALPHA_MAX) of double) -
- Blocal: magnitude of magnetic field at point (array(NTIME_MAX,NALPHA_MAX) - of double) - [nT] -
- Bmir or Bmirror: magnitude of magnetic field at mirror point (array(NTIME_MAX,NALPHA_MAX) - of double) - [nT] -
- Bmin: magnitude of magnetic field at equator - (array(NTIME_MAX,NALPHA_MAX) of double) - [nT] -
- XJ: I, related to second adiabatic invariant - (array(NTIME_MAX,NALPHA_MAX) of double) - [Re]
- MLT: magnetic local time in hours, (array(NTIME_MAX,NALPHA_MAX) - of double) - [hour] - -

- - POSIT: (note: size - varies. Changes from what's given here will be provided in the - function definitions). xGEO,yGEO and zGEO along the drift - shell, (array(3,1000,48) of double)
1st element: - x, y, z GEO coord, 2nd element: points along field line, 3rd - element: number of field lines. Note, sometimes the long - dimension is 3000 rather than 1000; see specific functions for - clarification.
- - Nposit: (note: size - varies. Changes from what's given here will be provided in the - function definitions) long integer array (48) providing the - number of points along the field line for each field line - traced in 2nd element of POSIT array (max 1000 for some functions, 3000 for others). -

- Note: Posit is organized as follow: array(xyz,along - bounce,drift index). Nposit tells how many of the 1000 (or 3000) points available are used to - described one bounce. -
-

- -
-
-
- Comments on adiabatic invariants: -
- J2=2*p*I/(2*π) where p is the particle momemtum - [kg m2 s-2 Re] -
- J3=q/(2*π) *Φ - [C nT Re2] -

-

-
- Below is provided an chart explaining the logic for the coding of Lm and Lstar - from the routine: -
-
-   -

- - -
-

MAKE_LSTAR -

-

DESCRIPTION: -

- This function allows one to compute magnetic coordinate - at any s/c position, i.e. L, L*, Blocal/Bmirror, Bequator. A set of internal/external - field can be selected.
-

INPUTS: -

- - ntime, kext, options, sysaxes, iyear, idoy, UT, x1, x2, x3, maginput

- - see Common Argument Definitions - -

- IMPORTANT: all inputs must be present. For those - which are not used a dummy value can be provided. -
-   - -

OUTPUTS: -

- - Lm, Lstar or Φ, Blocal, Bmin, XJ, MLT

- - see Common Argument Definitions - -

-
-

-

CALLING SEQUENCE FROM MATLAB: -

- [Lm,Lstar,Blocal,Bmin,J,MLT] = onera_desp_lib_make_lstar(kext,options,sysaxes,matlabd,x1,x2,x3,maginput) -
-

CALLING SEQUENCE FROM IDL: -

- result = call_external(lib_name, 'make_lstar_', ntime,kext,options,sysaxes,iyear,idoy,ut, - x1,x2,x3, maginput, lm,lstar,blocal,bmin,xj,mlt, /f_value) -
-   -

CALLING SEQUENCE FROM FORTRAN: -

- call make_lstar1(ntime,kext,options,sysaxes,iyear,idoy,ut, - x1,x2,x3, maginput, lm,lstar,blocal,bmin,xj,mlt) -

EXAMPLE CALLING SEQUENCE FROM PYTHON: -

- - model = MagFields()
- LLA = {'x1':651, 'x2':63, 'x3':20, 'dateTime':'2015-02-02T06:12:43'}
- maginput = {'Kp':40}
- output_dictionary = model.make_lstar(LLA, maginput)
- -

-

-

LANDI2LSTAR -

-

DESCRIPTION: -

- This function allows one to compute magnetic coordinate - at any s/c position, i.e. L, L*, Blocal/Bmirror, Bequator. A set of internal/external - field can be selected. Right now this routine differs from MAKE_LSTAR because L* - is deduced from Lm, I and day of year empirically. This is set only for IGRF+Olson-Pfitzer quiet - field model (kext can only be 5). The errors in L* values are less than 2%.
- -

INPUTS: -

- - ntime, kext, options, sysaxes, iyear, idoy, UT, x1, x2, x3, maginput - -

- - see Common Argument Definitions - -

- - IMPORTANT: all inputs must be present. For those - which are not used a dummy value can be provided. - -

OUTPUTS: -

- - Lm, Lstar or Φ, Blocal, Bmin, XJ, MLT

- - see Common Argument Definitions - -

- -

CALLING SEQUENCE FROM MATLAB: -

- [Lm,Lstar,Blocal,Bmin,J,MLT] = onera_desp_lib_landi2lstar(kext,options,sysaxes,matlabd,x1,x2,x3,maginput) -
-

CALLING SEQUENCE FROM IDL: -

- result = call_external(lib_name, 'landi2lstar_', ntime,kext,options,sysaxes,iyear,idoy,ut, - x1,x2,x3, maginput, lm,lstar,blocal,bmin,xj,mlt, /f_value) -
-   -

CALLING SEQUENCE FROM FORTRAN: -

- call landi2lstar1(ntime,kext,options,sysaxes,iyear,idoy,ut, - x1,x2,x3, maginput, lm,lstar,blocal,bmin,xj,mlt) -

-

-

EMPIRICALLSTAR -

-

DESCRIPTION: -

- This function allows one to compute L* empirically being given Lm, I and day of year. - This is set only for IGRF+Olson-Pfitzer quiet - field model (kext can only be 5) so Lm and I provided as input must be computed with this field. The errors in L* values are less than 2%.
- - - - - - - - -

INPUTS: -

- - ntime, kext, options, iyearsat, idoy, maginput, Lm, XJ - - -

- - see Common Argument Definitions - -

- - IMPORTANT: all inputs must be present. For those - which are not used a dummy value can be provided. - -

OUTPUTS: -

- - Lstar or Φ

- - see Common Argument Definitions - -

- - -

CALLING SEQUENCE FROM MATLAB: -

- Lstar = onera_desp_lib_empiricallstar(kext,options,matlabd,maginput,Lm,J) -
-

CALLING SEQUENCE FROM IDL: -

- result = call_external(lib_name, 'empiricalLstar_', ntime,kext,options,iyearsat,idoy, - maginput, lm,xj,lstar, /f_value) -
-   -

CALLING SEQUENCE FROM FORTRAN: -

- call EmpiricalLstar1(ntime,kext,options,iyearsat,idoy,maginput, - lm,xj,lstar) -

-
-

-

-

MAKE_LSTAR_SHELL_SPLITTING -

-

DESCRIPTION: -

- This function allows one to compute the magnetic coordinates - at any s/c position and pitch-angle, i.e. L, L*, Bmirror, Bequator. A set of internal/external - field can be selected. -

INPUTS: -

- - ntime, Nipa, kext, options, sysaxes, iyear, idoy, UT, x1, x2, x3, alpha, maginput

- - see Common Argument Definitions - -

- IMPORTANT: all inputs must be present. For those - which are not used a dummy value can be provided. -
-   -

-

OUTPUTS: -

- - Lm, Lstar or Φ, Blocal, Bmin, XJ, MLT

- - see Common Argument Definitions - -

CALLING SEQUENCE FROM MATLAB: -

- [Lm,Lstar,Bmirror,Bmin,J,MLT] = onera_desp_lib_make_lstar_shell_splitting(kext,options,sysaxes,matlabd,x1,x2,x3,alpha,maginput) -
-

CALLING SEQUENCE FROM IDL: -

- result = call_external(lib_name, 'make_lstar_shell_splitting_', - ntime,Npa,kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3,alpha,maginput,lm,lstar,blocal,bmin,xj,mlt, - /f_value) -
-   -

CALLING SEQUENCE FROM FORTRAN: -

- call make_lstar_shell_splitting1(ntime,Npa,kext,options,sysaxes,iyear,idoy,ut, - x1,x2,x3, alpha,maginput,lm,lstar,blocal,bmin,xj,mlt) -

-
-

-

-

LANDI2LSTAR_SHELL_SPLITTING -

-

DESCRIPTION: -

- This function allows one to compute the magnetic coordinates - at any s/c position and pitch-angle, i.e. L, L*, Bmirror, Bequator. A set of internal/external - field can be selected. - Right now this routine differs from MAKE_LSTAR_SHELL_SPLITTING because L* is deduced from Lm, I and day of year empirically. - This is set only for IGRF+Olson-Pfitzer quiet field model (kext can only be 5). - The errors in L* values are less than 2%. - - - -

INPUTS: -

- - ntime, Nipa, kext, options, sysaxes, iyear, idoy, UT, x1, x2, x3, alpha, maginput

- - see Common Argument Definitions - -

- IMPORTANT: all inputs must be present. For those - which are not used a dummy value can be provided. -
-   -

-

OUTPUTS: -

- - Lm, Lstar or Φ, Bmirror, Bmin, XJ, MLT

- - see Common Argument Definitions -

- -

CALLING SEQUENCE FROM MATLAB: -

- [Lm,Lstar,Bmirror,Bmin,J,MLT] = onera_desp_lib_landi2lstar_shell_splitting(kext,options,sysaxes,matlabd,x1,x2,x3,alpha,maginput) -
-

CALLING SEQUENCE FROM IDL: -

- result = call_external(lib_name, 'landi2lstar_shell_splitting_', - ntime,Npa,kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3,alpha,maginput,lm,lstar,blocal,bmin,xj,mlt, - /f_value) -
-   -

CALLING SEQUENCE FROM FORTRAN: -

- call landi2lstar_shell_splitting1(ntime,Npa,kext,options,sysaxes,iyear,idoy,ut, - x1,x2,x3, alpha,maginput,lm,lstar,blocal,bmin,xj,mlt) -

-
-

-

-

DRIFT_SHELL -

-

DESCRIPTION: -

- This function traces a full drift shell for particles - that have their mirror point at the input location.  The output is a full array - of positions of the drift shell, usefull for plotting and visualisation - (for just the points on the drift-bounce orbit, use DRIFT_BOUNCE_ORBIT). A - set of internal/external field can be selected. -

INPUTS: -

- - - - -

INPUTS: -

- - kext, options, sysaxes, iyear, idoy, UT, x1, x2, x3, maginput

- - see Common Argument Definitions - -

- IMPORTANT: all inputs must be present. For those - which are not used a dummy value can be provided. -
-   -

-

OUTPUTS: -

- - Lm, Lstar or Φ, Blocal, Bmin, XJ, POSIT, Nposit
- Blocal is (1000,48), Lm, Lstar/Φ, Bmin, and XJ are a scalars

- - see Common Argument Definitions - -

CALLING SEQUENCE FROM MATLAB: -

- [Lm,Lstar,Blocal,Bmin,J,POSIT] = onera_desp_lib_drift_shell(kext,options,sysaxes,matlabd,x1,x2,x3,maginput) -
-

CALLING SEQUENCE FROM IDL: -

- result = call_external(lib_name, 'drift_shell_',  - kext,options,sysaxes,iyear,idoy,ut,  x1,x2,x3, maginput, lm,lstar,blocal,bmin,xj,posit,Nposit,  - /f_value) -
-   -

CALLING SEQUENCE FROM FORTRAN: -

- call drift_shell1(kext,options,sysaxes,iyear,idoy,ut, - x1,x2,x3, maginput, lm,lstar,blocal,bmin,xj,posit,Nposit) -

EXAMPLE CALLING SEQUENCE FROM PYTHON: -

- - model = MagFields()
- LLA = {'x1':651, 'x2':63, 'x3':20, 'dateTime':'2015-02-02T06:12:43'}
- maginput = {'Kp':40}
- output_dictionary = model.drift_shell(LLA, maginput)
- -

-
-

-

-

DRIFT_BOUNCE_ORBIT -

-

DESCRIPTION: -

- This function traces a full - drift-bounce orbit for particles with a specified pitch angle at - the input location.  The output is a full array of positions - of the drift-bounce orbit, usefull for computing drift-bounce - averages. Key differences from DRIFT_SHELL: (1) only positions between - mirror points are returned, (2) 25 rather than 48 azimuths - are returned, (3) Lstar accuracy respects options(3) and - options(4), (4) a new parameter R0 is required which specifies the - minimum radial distance allowed along the drift path (usually - R0=1, but use R0<1 in the drift loss cone), (5) hmin and - hmin_lon outputs provide the altitude and longitude (GDZ) of the - minimum altitude point along the orbit (among those traced, not - just those returned). A set of - internal/external field can be selected. - - -

INPUTS: -

- kext, options, sysaxes, iyear, idoy, UT, x1, x2, x3, alpha, maginput, R0

- - see Common Argument Definitions - -

- IMPORTANT: all inputs must be present. For those - which are not used a dummy value can be provided. -
-   -

OUTPUTS: -

- - Lm, Lstar, Blocal, Bmin, Bmirror, XJ, POSIT, Nposit, hmin, hmin_lon
- Note: POSIT is size (3,1000,25) and Nposit is size (25)
- Blocal is (1000,25), Lm, Lstar/Φ, Bmin, Bmirror, XJ, hmin, and hmin_lon are a scalars

- - see Common Argument Definitions - -

- hmin: double, minimum altitude, GDZ, km, along the drift orbit -
- hmin_lon: double, longitude, GDZ, degrees, at hmin. -
- -

CALLING SEQUENCE FROM MATLAB: -

- [Lm,Lstar,Blocal,Bmin,Bmir,J,POSIT,hmin,hmin_lon] = onera_desp_lib_drift_bounce_orbit(kext,options,sysaxes,matlabd,x1,x2,x3,alpha,maginput,R0) -
-

CALLING SEQUENCE FROM IDL: -

- result = call_external(lib_name, 'drift_bounce_orbit2_',  - kext,options,sysaxes,iyear,idoy,ut,  x1,x2,x3,alpha, maginput,R0, lm,lstar,blocal,bmin,bmir,xj,posit,Nposit,hmin,hmin_lon,  - /f_value) -
-   -

CALLING SEQUENCE FROM FORTRAN: -

- call drift_bounce_orbit2_1(kext,options,sysaxes,iyear,idoy,ut, - x1,x2,x3,alpha, maginput,R0 lm,lstar,blocal,bmin,bmir,xj,posit,Nposit,hmin,hmin_lon) -

-
-

-

-

FIND_MIRROR_POINT -

-

DESCRIPTION: -

- This function finds the magnitude and location of the - mirror point along a field line traced from any given location and local pitch-angle - for a set of internal/external field to be selected. 
- - - - -

INPUTS: -

- kext, options, sysaxes, iyear, idoy, UT, x1, x2, x3, alpha, maginput

- - see Common Argument Definitions - -

- IMPORTANT: all inputs must be present. For those - which are not used a dummy value can be provided. -
-   -

OUTPUTS: -

- - Blocal, Bmir, POSIT
- Blocal and Bmir are scalars. POSIT is size (3) and provides the GEO coordinaets of the mirror point in Re. - - see Common Argument Definitions - -

CALLING SEQUENCE FROM MATLAB: -

- [Blocal,Bmirror,xGEO] = onera_desp_lib_find_mirror_point(kext,options,sysaxes,matlabd,x1,x2,x3,alpha,maginput) -
-

CALLING SEQUENCE FROM IDL: -

- result = call_external(lib_name,  'find_mirror_point_', - kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3,alpha,maginput, blocal,bmir,posit, /f_value) -
-   -

CALLING SEQUENCE FROM FORTRAN: -

- call find_mirror_point1(kext,options,sysaxes,iyear,idoy,ut, - x1,x2,x3,alpha, maginput,blocal,bmir,posit) -

EXAMPLE CALLING SEQUENCE FROM PYTHON: -

- - model = MagFields()
- LLA = {'x1':651, 'x2':63, 'x3':20, 'dateTime':'2015-02-02T06:12:43'}
- maginput = {'Kp':40}
- alpha = 90
- output_dictionary = model.find_mirror_point(LLA, maginput, alpha)
- -

-
-

-

-

FIND_MAGEQUATOR -

-

DESCRIPTION: -

- This function finds the GEO coordinates of the magnetic - equator along the field line starting from input location for a set of internal/external - field to be selected. 
- -

INPUTS: -

- - kext, options, sysaxes, iyear, idoy, UT, x1, x2, x3, maginput

- - see Common Argument Definitions - -

- IMPORTANT: all inputs must be present. For those - which are not used a dummy value can be provided. -
-   - -

OUTPUTS: -

- Bmin: magnitude of magnetic field at equator - (double) -

- POSIT: xGEO,yGEO and zGEO of the magnetic equator - location, (array(3) of double) -

-

CALLING SEQUENCE FROM MATLAB: -

- [Bmin,xGEO] = onera_desp_lib_find_magequator(kext,options,sysaxes,matlabd,x1,x2,x3,maginput) -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'find_magequator_',  - kext,options,sysaxes,iyear,idoy,ut,  x1,x2,x3, maginput, bmin,posit,  /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call find_magequator1(kext,options,sysaxes,iyear,idoy,ut,  - x1,x2,x3, maginput,bmin,posit) -

EXAMPLE CALLING SEQUENCE FROM PYTHON: -

- - model = MagFields()
- LLA = {'x1':651, 'x2':63, 'x3':20, 'dateTime':'2015-02-02T06:12:43'}
- maginput = {'Kp':40}
- output_dictionary = model.find_magequator(LLA, maginput)
- -

-
-

-

-

FIND_FOOT_POINT -

-

DESCRIPTION: -

- This function finds the of the field line crossing a specified altitude in a specified hemisphere - for a set of internal/external field to be selected. 
- -

INPUTS: -

- - kext, options, sysaxes, iyear, idoy, UT, x1, x2, x3, stop_alt, hemi_flag, maginput

- - See Common Argument Definitions - -

- stop_alt: double, desired altitude of field-line crossing, km. -

-

- hemi_flag: long integer, hemisphere flag. -

-
- 0   = same magnetic hemisphere as starting point
- +1   = northern magnetic hemisphere
- -1   = southern magnetic hemisphere
- +2   = opposite magnetic hemisphere as starting point
-
- -

- IMPORTANT: all inputs must be present. For those - which are not used a dummy value can be provided. -
-   -

-

OUTPUTS: -

- XFOOT: location of foot point, GDZ, (array(3) of double)
- BFOOT: magnetic field vector at foot point, GEO, nT, (array(3) of double)
- BFOOTMAG: magnetic field magnitude at foot point, GEO, nT, (array(3) of double)
-   -

CALLING SEQUENCE FROM MATLAB: -

- [Xfoot,Bfoot,BfootMag] = onera_desp_lib_find_foot_point(kext,options,sysaxes,matlabd,x1,x2,x3,stop_alt,hemi_flag,maginput) -
-

CALLING SEQUENCE FROM IDL: -

- result = call_external(lib_name,  'find_foot_point_', - kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3,stop_alt,hemi_flag,maginput, xfoot,bfoot,bfootmag, /f_value) -
-   -

CALLING SEQUENCE FROM FORTRAN: -

- - call find_foot_point1(kext,options,sysaxes,iyearsat,idoy,UT,xIN1,xIN2,xIN3,stop_alt,hemi_flag,maginput,XFOOT,BFOOT,BFOOTMAG) - -

EXAMPLE CALLING SEQUENCE FROM PYTHON: -

- - model = MagFields()
- LLA = {'x1':651, 'x2':63, 'x3':20, 'dateTime':'2015-02-02T06:12:43'}
- maginput = {'Kp':40}
- stopAlt = 100
- hemiFlag = 0
- output_dictionary = model.find_foot_point(LLA, maginput, stopAlt, hemiFlag)
- -

-
-

-

-

GET_FIELD -

-

DESCRIPTION: -

- This function is deprecated. Use GET_FIELD_MULTI instead. - -
- -
-

-

GET_FIELD_MULTI -

-

DESCRIPTION: -

- This function computes the GEO vector of the magnetic - field at input location for a set of internal/external magnetic field to be selected. 
-   -

INPUTS: -

- - ntime, kext, options, sysaxes, iyear, idoy, UT, x1, x2, x3, maginput

- - See Common Argument Definitions - - -
- IMPORTANT: all inputs must be present. For those - which are not used a dummy value can be provided. - -

-

OUTPUTS: -

- Bgeo: BxGEO,ByGEO and BzGEO of the magnetic field - (nT), (array(3,NTIME_MAX) of double) -
- Bl: magnitude of magnetic field (array(NTIME_MAX) of double) (nT) -
-   -

CALLING SEQUENCE FROM MATLAB: -

- [Bgeo,B] = onera_desp_lib_get_field(kext,options,sysaxes,matlabd,x1,x2,x3,maginput) -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'get_field_multi_idl_',ntime,kext,options,sysaxes,iyear,idoy,ut, - x1,x2,x3, maginput,Bgeo, Bl,  /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call GET_FIELD_MULTI(ntime,kext,options,sysaxes,iyear,idoy,ut, - x1,x2,x3, maginput,Bgeo,Bl) -

- -   -

EXAMPLE CALLING SEQUENCE FROM PYTHON: -

- - model = MagFields()
- LLA = {'x1':651, 'x2':63, 'x3':20, 'dateTime':'2015-02-02T06:12:43'}
- maginput = {'Kp':40}
- output_dictionary = model.get_field_multi(LLA, maginput)
- -

-
- - - -

-

-

GET_BDERIVS -

-

DESCRIPTION: -

- This function computes the magnetic field and its 1st-order derivatives - at each input location for a set of internal/external magnetic field to be selected. 
-   -

INPUTS: -

- - ntime, kext, options, sysaxes, dX, iyear, idoy, UT, x1, x2, x3, maginput

- - See Common Argument Definitions - -

- - dX: dX is the step size, in RE for the numerical derivatives (recommend 1E-3), double scalar. - -

- IMPORTANT: all inputs must be present. For those - which are not used a dummy value can be provided. - -

-

OUTPUTS: -

- Bgeo: BxGEO,ByGEO and BzGEO of the magnetic field - (nT), (array(3,NTIME_MAX) of double) -
- Bmag: magnitude of magnetic field (array(NTIME_MAX) of double) (nT) -
- gradBmag: gradient (GEO) of magnitude of magnetic field (array(3,NTIME_MAX) of double) (nT) -
- diffB: derivatives of magnetic field vector (array(3,3,NTIME_MAX) of double) (nT)
- diffB(i,j,t) = dB_i/dx_j at t'th location. GEO coordinates. -
-   -

CALLING SEQUENCE FROM MATLAB: -

- [Bgeo,B,gradBmag,diffB] = onera_desp_lib_get_bderivs(kext,options,sysaxes,matlabd,x1,x2,x3,maginput,...) -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'get_bderivs_idl',ntime,kext,options,sysaxes,dX,iyear,idoy,ut, - x1,x2,x3, maginput,Bgeo,Bmag,gradBmag,diffB,  /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call GET_BDERIVS(ntime,kext,options,sysaxes,dX,iyear,idoy,ut, - x1,x2,x3, maginput,Bgeo,Bmag,gradBmag,diffB) -

-
- -

-

-

COMPUTE_GRAD_CURV_CURL -

-

DESCRIPTION: -

- This function computes gradient and curvature force factors and div/curl of B - from the outputs of GET_BDERIVS 
-   -

INPUTS: -

- - ntime, Bgeo, Bmag, gradBmag, diffB defined as for GET_BDERIVS

- -

-

OUTPUTS: -

- - grad_par: gradient of Bmag along B nT/RE, (array(NTIME_MAX) of double)
- grad_perp: gradient of Bmag perpendicular to B nT/RE (array(3,NTIME_MAX) of double)
- grad_drift: (bhat x grad_perp)/B, 1/RE (part of gradient drift velocity) (array(3,NTIME_MAX) of double)
- curvature: (bhat dot grad)bhat, 1/RE (part of curvature force) (array(3,NTIME_MAX) of double)
- Rcurv: 1/|curvature| RE (radius of curvature) (array(3,NTIME_MAX) of double)
- curv_drift: (bhat x curvature), 1/RE (part of curvature drift) (array(NTIME_MAX) of double)
- curlB: curl of B (nT/RE) (part of electrostatic current term) (array(3,NTIME_MAX) of double)
- divB: divergence of B (nT/RE) (should be zero!) (array(NTIME_MAX) of double)
- -

- -   -

CALLING SEQUENCE FROM MATLAB: -

- [grad_par,grad_perp,grad_drift,curvature,Rcurv,curv_drift,curlB,divB] = onera_desp_lib_compute_grad_curv_curl(Bgeo,B,gradBmag,diffB) -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'compute_grad_curv_idl',ntime,Bgeo,Bmag,gradBmag,diffB, - grad_par,grad_perp,grad_drift,curvature,Rcurv,curv_drift,curlB,divB, -   /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- - call COMPUTE_GRAD_CURV_CURL(ntime,Bgeo,Bmag,gradBmag,diffB, - grad_par,grad_perp,grad_drift,curvature,Rcurv,curv_drift,curlB,divB) -

-
- -

-

-

TRACE_FIELD_LINE2 -

-

DESCRIPTION: -

- This function traces a full field line which crosses - the input position.  The output is a full array of positions of the field line, - usefull for plotting and visualisation for a set of internal/external fields to be - selected. A new option (R0) for TRACE_FIELD_LINE2 allows user to specify the radius (RE) - of the reference surface between which the line is traced (R0=1 in TRACE_FIELD_LINE)  
- - - -

INPUTS: -

- - kext, options, sysaxes, iyear, idoy, UT, x1, x2, x3, maginput, R0

- - See Common Argument Definitions - -

- R0: double, specifies radius of reference surface - between which field line is traced. -

-
- IMPORTANT: all inputs must be present. For those - which are not used a dummy value can be provided. -
-   -

OUTPUTS: -

- - - Lm, Blocal, Bmin, XJ, POSIT, Nposit

- See Common Argument Definitions
- POSIT is (3,3000), Nposit is a scalar. - -   -

-
-

-

CALLING SEQUENCE FROM MATLAB: -

- [Lm,Blocal,Bmin,J,POSIT] = onera_desp_lib_trace_field_line(kext,options,sysaxes,matlabd,x1,x2,x3,maginput,R0) -
-

CALLING SEQUENCE FROM IDL: -

- result = call_external(lib_name, 'trace_field_line2_',  - kext,options,sysaxes,iyear,idoy,ut,  x1,x2,x3,maginput,R0,lm,blocal,bmin,xj,posit,Nposit,  - /f_value) -
-   -

CALLING SEQUENCE FROM FORTRAN: -

- call trace_field_line2_1(kext,options,sysaxes,iyear,idoy,ut, - x1,x2,x3, maginput,R0, lm,blocal,bmin,xj,posit,Nposit) -

EXAMPLE CALLING SEQUENCE FROM PYTHON: -

- - model = MagFields()
- LLA = {'x1':651, 'x2':63, 'x3':20, 'dateTime':'2015-02-02T06:12:43'}
- maginput = {'Kp':40}
- output_dictionary = model.trace_field_line(LLA, maginput)
- -

-
-

-

-

TRACE_FIELD_LINE_TOWARD_EARTH -

-

DESCRIPTION: -

- This function traces a field line from - the input position to the Earth surface.  The output is a full array of positions of the field line, - usefull for plotting and visualisation for a set of internal/external fields to be - selected. 
-

INPUTS: -

- - kext, options, sysaxes, iyear, idoy, UT, x1, x2, x3, maginput, ds

- - See Common Argument Definitions - -

- ds: double, Integration step along field line (in Re). -

-
- IMPORTANT: all inputs must be present. For those - which are not used a dummy value can be provided. -
-   -

OUTPUTS: -

- - POSIT, Nposit

- See Common Argument Definitions
- POSIT is (3,3000), Nposit is a scalar. - -

-

CALLING SEQUENCE FROM MATLAB: -

- POSIT = onera_desp_lib_trace_field_line_towards_earth(kext,options,sysaxes,matlabd,x1,x2,x3,maginput,ds) -
-

CALLING SEQUENCE FROM IDL: -

- result = call_external(lib_name, 'trace_field_line_towards_earth_',  - kext,options,sysaxes,iyear,idoy,ut,  x1,x2,x3, maginput, ds,posit,Nposit,  - /f_value) -
-   -

CALLING SEQUENCE FROM FORTRAN: -

- call trace_field_line_towards_earth1(kext,options,sysaxes,iyear,idoy,ut, - x1,x2,x3, maginput, ds,posit,Nposit) -

-

-

-

GET_MLT -

-

DESCRIPTION: -

- Routine to get Magnetic Local Time (MLT) from a Cartesian - GEO position and date -
-   -

INPUTS: -

- iyr : long integer year -
- idoy : long integer day of year -
- secs : UT in seconds - double -
- xGEO : 3D array (double) of cartesian position - in GEO (Re) -
-   -

OUTPUTS: -

- MLT: Magnetic Local Time (hours) - double -
- -
-   -

CALLING SEQUENCE FROM MATLAB: -

- MLT = onera_desp_lib_get_mlt(matlabd,xGEO) -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'get_mlt_', iyr,idoy,secs,xGEO,MLT, - /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call get_mlt1(iyr,idoy,secs,xGEO,MLT)
-
- - - -
-

GET_HEMI -

-

DESCRIPTION: -

- This routine is deprecated. Use GET_HEMI_MULTI instead. - -
- - -
-

GET_HEMI_MULTI -

-

DESCRIPTION: -

- This function computes in which magnetic hemisphere - is the input location for a set of internal/externalmagnetic field to select. 
-
-   -

INPUTS: -

- - - ntime, kext, options, sysaxes, iyear, idoy, UT, x1, x2, x3, maginput

- - See Common Argument Definitions - - -

- IMPORTANT: all inputs must be present. For those - which are not used a dummy value can be provided. -

-

OUTPUTS: -

- xHEMI: +1 means Northern magnetic hemisphere, - -1 means Southern magnetic hemisphere, 0 means cannot be defined (magnetic field not - valid) - long 
-   -

CALLING SEQUENCE FROM MATLAB: -

- [xHEMI] = onera_desp_lib_get_hemi(kext,options,sysaxes,matlabd,x1,x2,x3,maginput) -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'get_hemi_multi_idl_',ntime,kext,options,sysaxes,iyear,idoy,ut, - x1,x2,x3, maginput,xHEMI,  /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call GET_HEMI_MULTI(ntime,kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3, - maginput,xHEMI) -

-
-

-
- - - -
-

LSTAR_PHI -

-

DESCRIPTION: -

- This function allows one to convert L* to Φ or - vice versa. -

INPUTS: -

- - ntime, whichinv, options, iyear, idoy

- See Common Argument Definitions
- NOTE: options does not support user-supplied internal field model.
- -

- whichinv: long integer to select which conversion - to perform 
-

- -
1   = Lstar - to Φ 
- 2   = Φ to Lstar -
- -
-

- IMPORTANT: all inputs must be present. For those - which are not used a dummy value can be provided. -
-   -

-

INPUTS or OUTPUTS (according - to whichinv): -

- - - Lstar, Phi - See Common Argument Definitions
- -

- Phi: Φ=2π*Bo/Lstar [nT Re2] - (array(GET_IRBEM_NTIME_MAX()) of double)  -
-

-

CALLING SEQUENCE FROM MATLAB: -

- out = onera_desp_lib_lstar_phi(which,options,matlabd,in) -
-

CALLING SEQUENCE FROM IDL: -

- result = call_external(lib_name, lstar_phi_', ntime,whichinv,options,iyear,idoy,lstar,phi, - /f_value) -
-   -

CALLING SEQUENCE FROM FORTRAN: -

- call lstar_phi1(ntime,whichinv,options,iyear,idoy,lstar,phi) -
-
-
-

COORD_TRANS -

-

DESCRIPTION: -

- Deprecated. Use COORD_TRANS_VEC - -
-

-

COORD_TRANS_VEC -

-

DESCRIPTION: -

- Generic coordinates transformation from one geophysical or - heliospheric coordinate system to another. Handles up to GET_IRBEM_NTIME_MAX() times at once. -
-   -

INPUTS: -

- - - ntime, sysaxesIN, sysaxesOUT, iyr, idoy, secs, xIN

- - For definitions of the coordinate systems, and notes on transformations, see Common Argument - Definitions. -

- sysaxesIN: long integer indicating input - coordinates system 
- sysaxesOUT : long integer indicating - output coordinates system -
- xIN : array (3,NTIME_MAX) of double with position - in input coordinates system. - - -

- IMPORTANT: all inputs must be present. For those - which are not used a dummy value can be provided. -
-

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - Input -

- GDZ (0) -

- 		-

- GEO (1) -

- 		-

- GSM (2) -

- 		-

- GSE (3) -

- 		-

- SM(4) -

- 		-

- GEI(5) -

- 		-

- MAG (6) -

- 		-

- SPH(7) -

- 		-

- RLL(8) -

- 		-

- HEE (9) -

- 		-

- HAE(10) -

- 		-

- HEEQ (11) -

- 		-

- ECI TOD (12) -

- 		-

- J2000 (13) -

- 		-

- TEME (14) -

-
- Output -
-

- GDZ (0) -

- 		- - - - - - - - - - - - - - -
-

- GEO (1) -

- 		- - - - - - - - - - - - - - -
-

- GSM (2) -

- 		- - - - - - - - - - - - - - -
-

- GSE (3) -

- 		- - - - - - - - - - - - - - -
-

- SM (4) -

- 		- - - - - - - - - - - - - - -
-

- GEI (5) -

- 		- - - - - - - - - - - - - - -
-

- MAG (6) -

- 		- - - - - - - - - - - - - - -
-

- SPH (7) -

- 		- - - - - - - - - - - - - - -
-

- RLL (8) -

- 		- - - - - - - - - - - - - - -
-

- HEE (9) -

- 		- - - - - - - - - - - - - - -
-

- HAE (10) -

- 		- - - - - - - - - - - - - - -
- HEEQ (11) - - - - - - - - - - - - - - -
- ECI TOD (12) - - - - - - - - - - - - - - -
- J2000 (13) - - - - - - - - - - - - - - -
- TEME (14) - - - - - - - - - - - - - - -
-

- Table: Available coordinates transformation:
-  ⇒Transformation - implemented -
-  ⇒Will - not crash but not very usefull  -
-  ⇒Not - implemented -

-

OUTPUTS: -

- xOUT : array (3,NTIME_MAX) of double with position - in output coordinates system. (systems defined by sysaxesOUT) -
-   -

CALLING SEQUENCE FROM MATLAB: -

- Y=onera_desp_lib_coord_trans(X,rotation,matlabd) 
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'coord_trans_vec_', - ntime,sysaxesIN,sysaxesOUT,iyr,idoy,secs,xIN,xOUT, /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call coord_trans_vec1(ntime,sysaxesIN,sysaxesOUT,iyr,idoy,secs,xIN,xOUT) -

-

-

-

-

-

GEO2GSM -

-

DESCRIPTION: -

-

- Routine to transform Cartesian GEO to cartesian GSM - coordinates -
-   -

-

INPUTS: -

-

- iyr : long integer year -
- idoy : long integer day of year -
- secs : UT in seconds - double -
- xGEO : 3D array (double) of cartesian position - in GEO (Re) -
-   -

-

OUTPUTS: -

-

- psi : angle for GSM coordinate - double -
- xGSM : 3D array (double) of cartesian position in GSM (Re) -
-   -

-

CALLING SEQUENCE FROM MATLAB: -

-

- xGSM = onera_desp_lib_rotate(xGEO,'geo2gsm',matlabd);
- [xGSM,psi] = onera_desp_lib_rotate(xGEO,'geo2gsm',matlabd); -
-

-

CALLING SEQUENCE from IDL: -

-

- result = call_external(lib_name, 'geo2gsm_', iyr,idoy,secs,psi,xGEO,xGSM, - /f_value) -
-   -

-

CALLING SEQUENCE from FORTRAN: -

-

- call geo2gsm1(iyr,idoy,secs,psi,xGEO,xGSM) -

-

-
-
-

-

-

GSM2GEO -

-

DESCRIPTION: -

- Routine to transform Cartesian GSM to cartesian GEO - coordinates -

INPUTS: -

- iyr : long integer year -
- idoy : long integer day of year -
- secs : UT in seconds - double -
- xGSM : 3D array (double) of cartesian position - in GSM (Re) -
-   -

OUTPUTS: -

- psi : angle for GSM coordinate - double -
- xGEO : 3D array (double) of cartesian position - in GEO (Re) -
-   -

CALLING SEQUENCE FROM MATLAB: -

- xGEO = onera_desp_lib_rotate(xGSM,'gsm2geo',matlabd);
- [xGEO,psi] = onera_desp_lib_rotate(xGSM,'gsm2geo',matlabd); -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'gsm2geo_', iyr,idoy,secs,psi,xGSM,xGEO, - /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call gsm2geo1(iyr,idoy,secs,psi,xGSM,xGEO) -

-
-

-

-

GEO2GSE -

-

DESCRIPTION: -

- Routine to transform Cartesian GEO to cartesian GSM - coordinates -

INPUTS: -

- iyr : long integer year -
- idoy : long integer day of year -
- secs : UT in seconds - double -
- xGEO : 3D array (double) of cartesian position - in GEO (Re) -
-   -

OUTPUTS: -

- xGSE : 3D array (double) of cartesian position - in GSE (Re) -
-   -

CALLING SEQUENCE FROM MATLAB: -

- xGSE = onera_desp_lib_rotate(xGEO,'geo2gse',matlabd); -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'geo2gse_', iyr,idoy,secs,xGEO,xGSE, - /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call geo2gse1(iyr,idoy,secs,xGEO,xGSE) -

-
-

-

-

GSE2GEO -

-

DESCRIPTION: -

- Routine to transform Cartesian GSE to cartesian GEO - coordinates -
-   -

INPUTS: -

- iyr : long integer year -
- idoy : long integer day of year -
- secs : UT in seconds - double -
- xGSE : 3D array (double) of cartesian position - in GSE (Re) -
-   -

OUTPUTS: -

- xGEO : 3D array (double) of cartesian position - in GEO (Re) -
-   -

CALLING SEQUENCE FROM MATLAB: -

- xGEO = onera_desp_lib_rotate(xGSE,'gse2geo',matlabd); -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'gse2geo_', iyr,idoy,secs,xGSE,xGEO, - /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call gse2geo1(iyr,idoy,secs,xGSE,xGEO) -

-
-

-

-

GDZ2GEO -

-

DESCRIPTION: -

- Routine to transform GEODEZIC coordinates to cartesian - GEO coordinates -
-   -

INPUTS: -

- lati : latitude (degres) (double) -
- longi : East longitude (degres) (double) -
- alti : altitude (km) (double) -
-   -

OUTPUTS: -

- xx : xGEO (Re) (double) -
- yy : yGEO (Re) (double) -
- zz : zGEO (Re) (double) -
-   -

CALLING SEQUENCE FROM MATLAB: -

- ******NOTE ORDER OF GDZ COORDINATES********
- xGEO = onera_desp_lib_rotate([alti(:), lati(:), longi(:)],'gdz2geo');
- xx = xGEO(:,1); yy = xGEO(:,2); zz = xGEO(:,3); -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'gdz2geo_', lati,longi,alti,xx,yy,zz, - /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call gdz_geo(lati,longi,alti,xx,yy,zz) -

-
-

-

-

GEO2GDZ -

-

DESCRIPTION: -

- Routine to transform cartesian GEO coordinates to GEODEZIC - coordinates -
-   -

INPUTS: -

- xx : xGEO (Re) (double) -
- yy : yGEO (Re) (double) -
- zz : zGEO (Re) (double) -
-   -

OUTPUTS: -

- lati : latitude (degres) (double) -
- longi : East longitude (degres) (double) -
- alti : altitude (km) (double) -
-   -

CALLING SEQUENCE FROM MATLAB: -

- ******NOTE ORDER OF GDZ COORDINATES********
- xGDZ = onera_desp_lib_rotate([xx(:) yy(:) zz(:)],'geo2gdz');
- alti = xGDZ(:,1); lati = xGDZ(:,2); longi = xGDZ(:,3); -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'geo2gdz_', xx,yy,zz,lati,longi,alti, - /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call geo_gdz(xx,yy,zz,lati,longi,alti) -

-
-

-

-

GEO2GEI -

-

DESCRIPTION: -

- Routine to transform Cartesian GEO to cartesian GEI - coordinates -
-   -

INPUTS: -

- iyr : long integer year -
- idoy : long integer day of year -
- secs : UT in seconds -double -
- xGEO : 3D array (double) of cartesian position - in GEO (Re) -
-   -

OUTPUTS: -

- xGEI: 3D array (double) of cartesian position - in GEI (Re) -
-   -

CALLING SEQUENCE FROM MATLAB: -

- xGEI = onera_desp_lib_rotate(xGEO,'geo2gei',matlabd); -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'geo2gei_', iyr,idoy,secs,xGEO,xGEI, - /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call geo2gei1(iyr,idoy,secs,xGEO,xGEI) -

-
-

-

-

GEI2GEO -

-

DESCRIPTION: -

- Routine to transform Cartesian GEI to cartesian GEO - coordinates -
-   -

INPUTS: -

- iyr : long integer year -
- idoy : long integer day of year -
- secs : UT in seconds - double -
- xGEI : 3D array (double) of cartesian position - in GEI (Re) -
-   -

OUTPUTS: -

- xGEO: 3D array (double) of cartesian position - in GEO (Re) -
-   -

CALLING SEQUENCE FROM MATLAB: -

- xGEO = onera_desp_lib_rotate(xGEI,'gei2geo',matlabd); -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'gei2geo_', iyr,idoy,secs,xGEI,xGEO, - /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call gei2geo1(iyr,idoy,secs,xGEI,xGEO) -

-
-

-

-

GEO2SM -

-

DESCRIPTION: -

- Routine to transform Cartesian GEO to cartesian SM coordinates -
-   -

INPUTS: -

- iyr : long integer year -
- idoy : long integer day of year -
- secs : UT in seconds - double -
- xGEO : 3D array (double) of cartesian position - in GEO (Re) -
-   -

OUTPUTS: -

- xSM: 3D array (double) of cartesian position - in SM (Re) -
-   -

CALLING SEQUENCE FROM MATLAB: -

- xSM = onera_desp_lib_rotate(xGEO,'geo2sm',matlabd); -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'geo2sm_', iyr,idoy,secs,xGEO,xSM, - /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call geo2sm1(iyr,idoy,secs,xGEO,xSM) -

-
-

-

-

SM2GEO -

-

DESCRIPTION: -

- Routine to transform Cartesian SM to cartesian GEO coordinates -
-   -

INPUTS: -

- iyr : long integer year -
- idoy : long integer day of year -
- secs : UT in seconds - double -
- xSM : 3D array (double) of cartesian position - in SM (Re) -
-   -

OUTPUTS: -

- xGEO: 3D array (double) of cartesian position - in GEO (Re) -
-   -

CALLING SEQUENCE FROM MATLAB: -

- xGEO = onera_desp_lib_rotate(xSM,'sm2geo',matlabd); -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'sm2geo_', iyr,idoy,secs,xSM,xGEO, - /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call sm2geo1(iyr,idoy,secs,xSM,xGEO) -

-
-

-

-

GSM2SM -

-

DESCRIPTION: -

- Routine to transform Cartesian GSM to cartesian SM coordinates -
-   -

INPUTS: -

- iyr : long integer year -
- idoy : long integer day of year -
- secs : UT in seconds - double -
- xGSM : 3D array (double) of cartesian position - in GSM (Re) -
-   -

OUTPUTS: -

- xSM: 3D array (double) of cartesian position - in SM (Re) -
-   -

CALLING SEQUENCE FROM MATLAB: -

- xSM = onera_desp_lib_rotate(xGSM,'gsm2sm',matlabd); -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'gsm2sm_', iyr,idoy,secs,xGSM,xSM, - /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call gsm2sm1(iyr,idoy,secs,xGSM,xSM) -

-
-

-

-

SM2GSM -

-

DESCRIPTION: -

- Routine to transform Cartesian SM to cartesian GSM coordinates -
-   -

INPUTS: -

- iyr : long integer year -
- idoy : long integer day of year -
- secs : UT in seconds - double -
- xSM : 3D array (double) of cartesian position - in SM (Re) -
-   -

OUTPUTS: -

- xGSM: 3D array (double) of cartesian position - in GSM (Re) -
-   -

CALLING SEQUENCE FROM MATLAB: -

- xGSM = onera_desp_lib_rotate(xSM,'sm2gsm',matlabd); -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'sm2gsm_', iyr,idoy,secs,xSM,xGSM, - /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call sm2gsm1(iyr,idoy,secs,xSM,xGSM) -

-
-

-

-

GEO2MAG -

-

DESCRIPTION: -

- Routine to transform Cartesian GEO to cartesian MAG - coordinates -
-   -

INPUTS: -

- iyr : long integer year -
- xGEO : 3D array (double) of cartesian position - in GEO (Re) -
-   -

OUTPUTS: -

- xMAG: 3D array (double) of cartesian position - in MAG (Re) -
-   -

CALLING SEQUENCE FROM MATLAB: -

- xMAG = onera_desp_lib_rotate(xGEO,'geo2mag',matlabd); -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'geo2mag_', iyr,xGEO,xMAG, - /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call geo2mag1(iyr,xGEO,xMAG) -

-
-

-

-

MAG2GEO -

-

DESCRIPTION: -

- Routine to transform Cartesian MAG to cartesian GEO - coordinates -
-   -

INPUTS: -

- iyr : long integer year -
- xMAG : 3D array (double) of cartesian position - in MAG (Re) -
-   -

OUTPUTS: -

- xGEO: 3D array (double) of cartesian position - in GEO (Re) -
-   -

CALLING SEQUENCE FROM MATLAB: -

- xGEO = onera_desp_lib_rotate(xMAG,'mag2geo',matlabd); -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'mag2geo_', iyr,xMAG,xGEO, - /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call mag2geo1(iyr,xMAG,xGEO) -

-
-

-

-

SPH2CAR -

-

DESCRIPTION: -

- Routine to transform spherical coordinates to cartesian -
-   -

INPUTS: -

- r : radial distance (double) -
- lati: (degree) -
- longi: (degree) -
-   -

OUTPUTS: -

- x: 3D array (double) of cartesian position (same - unit as r) -
-   -

CALLING SEQUENCE FROM MATLAB: -

- xCAR = onera_desp_lib_rotate([r(:), lati(:), longi(:)],'sph2car'); -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'sph2car_', r,lati,longi,x, - /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call SPH_CAR(r,lati,longi,x) -

-
-

-

-

CAR2SPH -

-

DESCRIPTION: -

- Routine to transform cartesian coordinates to spherical -
-   -

INPUTS: -

- x : 3D array (double) of cartesian position -
-   -

OUTPUTS: -

- r : radial distance (double) - same unit as x -
- lati : (degree) -
- longi : (degree) -
-   -

CALLING SEQUENCE FROM MATLAB: -

- xSPH = onera_desp_lib_rotate(xCAR,'car2sph');
- r = xSPH(:,1); lati = xSPH(:,2); longi = xSPH(:,3); -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'car2sph_', x,r,lati,longi, - /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call CAR_SPH(x,r,lati,longi) -

-
-

-

-

-

-

RLL2GDZ -

-

DESCRIPTION: -

- Routine to transform radial distance, latitude, longitude - to altitude, latitude, longitude -
-   -

INPUTS: -

- r : radial distance (double) - Re -
- lati : (double- - degree) -
- longi : (double- degree) -
-   -

OUTPUTS: -

- alti : altitude (double) - km -
- -
-   -

CALLING SEQUENCE FROM MATLAB: -

- ******NOTE ORDER OF GDZ COORDINATES********
- xGDZ = onera_desp_lib_rotate([r(:), lati(:), longi(:)],'rll2gdz');
- alti = xGDZ(:,1); lati = xGDZ(:,2); longi = xGDZ(:,3); -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'rll2gdz_', r,lati,longi,alti, - /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call RLL_GDZ(r,lati,longi,alti) -
-

-
-

-

-

GSE2HEE -

-

DESCRIPTION: -

- Routine to transform geocentric coordinates GSE to heliospheric - coordinates HEE (Heliocentric Earth Ecliptic also sometime known as Heliospheric Solar - Ecliptic (HSE) -
-   -

INPUTS: -

- iyr : year (long)  -
- idoy: day - of year - January 1st is idoy=1 (long) 
- UT : Universal Time (double- seconds) -
- xGSE : 3D array (double) of cartesian position - in GSE (Re) -
-

OUTPUTS: -

- xHEE : 3D array (double) of cartesian position - in HEE (AU) -
- -
-   -

CALLING SEQUENCE FROM MATLAB: -

- xHEE = onera_desp_lib_rotate(xGSE,'gse2hee',matlabd); -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'gse2hee_', iyr,idoy,UT,xGSE,xHEE, - /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call gse2hee1(iyr,idoy,UT,xGSE,xHEE) -
-

-
-

-

-

HEE2GSE -

-

DESCRIPTION: -

- Routine to transform heliospheric coordinates HEE (Heliocentric - Earth Ecliptic also sometime known as Heliospheric Solar Ecliptic (HSE) to geocentric - coordinates GSE -
-   -

INPUTS: -

- iyr : year (long)  -
- idoy: day - of year - January 1st is idoy=1 (long) 
- UT : Universal Time (double- seconds) -
- xHEE : 3D array (double) of cartesian position - in HEE (AU) -
-

OUTPUTS: -

- xGSE : 3D array (double) of cartesian position - in GSE (Re) -
- -
-   -

CALLING SEQUENCE FROM MATLAB: -

- xGSE = onera_desp_lib_rotate(xHEE,'hee2gse',matlabd); -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'hee2gse_', iyr,idoy,UT,xHEE,xGSE, - /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call hee2gse1(iyr,idoy,UT,xHEE,xGSE) -
-

-
-

-

-

HEE2HAE -

-

DESCRIPTION: -

- Routine to transform heliospheric coordinates HEE (Heliocentric - Earth Ecliptic also sometime known as Heliospheric Solar Ecliptic (HSE) to heliospheric - coordinates HAE (Heliocentric Aries Ecliptic also sometime known as Heliospheric Solar - Ecliptic (HSE) -
-   -

INPUTS: -

- iyr : year (long)  -
- idoy: day - of year - January 1st is idoy=1 (long) 
- UT : Universal Time (double- seconds) -
- xHEE : 3D array (double) of cartesian position - in HEE (AU) -
-

OUTPUTS: -

- xHAE : 3D array (double) of cartesian position - in HAE (AU) -
- -
-   -

CALLING SEQUENCE FROM MATLAB: -

- xHAE = onera_desp_lib_rotate(xHEE,'hee2hae',matlabd); -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'hee2hae_', iyr,idoy,UT,xHEE,xHAE, - /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call hee2hae1(iyr,idoy,UT,xHEE,xHAE) -
-

-
-

-

-

HAE2HEE -

-

DESCRIPTION: -

- Routine to transform heliospheric coordinates HAE (Heliocentric - Aries Ecliptic also sometime known as Heliospheric Solar Ecliptic (HSE) to heliospheric - coordinates HEE (Heliocentric Earth Ecliptic also sometime known as Heliospheric Solar - Ecliptic (HSE) -
-   -

INPUTS: -

- iyr : year (long)  -
- idoy: day - of year - January 1st is idoy=1 (long) 
- UT : Universal Time (double- seconds) -
- xHAE : 3D array (double) of cartesian position - in HAE (AU) -
-

OUTPUTS: -

- xHEE : 3D array (double) of cartesian position - in HEE (AU) -
- -
-   -

CALLING SEQUENCE FROM MATLAB: -

- xHEE = onera_desp_lib_rotate(xHAE,'hae2hee',matlabd); -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'hae2hee_', iyr,idoy,UT,xHAE,xHEE, - /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call hae2hee1(iyr,idoy,UT,xHAE,xHEE) -
-

-
-

-

-

HAE2HEEQ -

-

DESCRIPTION: -

- Routine to transform heliospheric coordinates HAE (Heliocentric - Aries Ecliptic also sometime known as Heliospheric Solar Ecliptic (HSE) to heliospheric - coordinates HEEQ (Heliocentric Earth Equatorial also sometime known as Heliospheric - Solar (HS) -
-   -

INPUTS: -

- iyr : year (long)  -
- idoy: day - of year - January 1st is idoy=1 (long) 
- UT : Universal Time (double- seconds) -
- xHAE : 3D array (double) of cartesian position - in HAE (AU) -
-

OUTPUTS: -

- xHEEQ : 3D array (double) of cartesian position - in HEEQ (AU) -
- -
-   -

CALLING SEQUENCE FROM MATLAB: -

- xHEEQ = onera_desp_lib_rotate(xHAE,'hae2heeq',matlabd); -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'hae2heeq_', iyr,idoy,UT,xHAE,xHEEQ, - /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call hae2heeq1(iyr,idoy,UT,xHAE,xHEEQ) -
-

-
-

-

-

HEEQ2HAE -

-

DESCRIPTION: -

- Routine to transform heliospheric coordinates HEEQ (Heliocentric - Earth Equatorial also sometime known as Heliospheric Solar (HS) to heliospheric coordinates - HAE (Heliocentric Aries Ecliptic also sometime known as Heliospheric Solar Ecliptic - (HSE) -
-   -

INPUTS: -

- iyr : year (long)  -
- idoy: day - of year - January 1st is idoy=1 (long) 
- UT : Universal Time (double- seconds) -
- xHEEQ : 3D array (double) of cartesian position - in HEEQ (AU) -
-

OUTPUTS: -

- xHAE : 3D array (double) of cartesian position - in HAE (AU) -
- -
-   -

CALLING SEQUENCE FROM MATLAB: -

- xHAE = onera_desp_lib_rotate(xHEEQ,'heeq2hae',matlabd); -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'heeq2hae_', iyr,idoy,UT,xHEEQ,xHAE, - /f_value) -
-   -

CALLING SEQUENCE from FORTRAN: -

- call heeq2hae1(iyr,idoy,UT,xHEEQ,xHAE) -
-

-
-

-

-

JULDAY -

-

DESCRIPTION: -

- Calculate the Julian Day Number for a given month, day, - and year. -
-   -

INPUTS: -

- MONTH: Number of the desired month (1 = January, - ..., 12 = December). - long -

- DAY: Number of day of the month. - long -

-

- YEAR: Number of the desired year.Year parameters - must be valid values from the civil calendar. Years B.C.E. are represented as negative - integers. Years in the common era are represented as positive integers. In particular, - note that there is no year 0 in the civil calendar. 1 B.C.E. (-1) is followed by 1 - C.E. (1). - long -
-   -

-

OUTPUTS: -

- JULDAY returns the Julian Day Number (which begins - at noon) of the specified calendar date. - long -
-   -

CALLING SEQUENCE FROM MATLAB: -

- Not available, see MATLAB build-in routines -
-

CALLING SEQUENCE from IDL: -

- Not available, see IDL build-in routines -
-   -

CALLING SEQUENCE from FORTRAN: -

- Result = JULDAY(Year,Month, Day) -

-
-

-

-

CALDAT -

-

DESCRIPTION: -

- Return the calendar date given julian day. This is the - inverse of the function JULDAY. -
-   -

INPUTS: -

- JULIAN contains the Julian Day Number (which - begins at noon) of the specified calendar date. It should be a long integer. -
-   -

OUTPUTS: -

- MONTH: Number of the desired month (1 = January, - ..., 12 = December). - long -

- DAY: Number of day of the month. - long -

-

- YEAR: Number of the desired year. - long -
-   -

-

CALLING SEQUENCE FROM MATLAB: -

- Not available, see MATLAB build-in routines -
-

CALLING SEQUENCE from IDL: -

- Not available, see IDL build-in routines -
-   -

CALLING SEQUENCE from FORTRAN: -

- CALL CALDAT(julian, year,month, day) -

-
-

-

-

GET_DOY -

-

DESCRIPTION: -

- Calculate the day of year for a given month, day, and - year. -
-   -

INPUTS: -

- MONTH: Number of the desired month (1 = January, - ..., 12 = December). -

- DAY: Number of day of the month. -

-

- YEAR: Number of the desired year.Year parameters - must be valid values from the civil calendar. Years B.C.E. are represented as negative - integers. Years in the common era are represented as positive integers. In particular, - note that there is no year 0 in the civil calendar. 1 B.C.E. (-1) is followed by 1 - C.E. (1). -
-   -

-

OUTPUTS: -

- GET_DOY returns the day of year of the specified - calendar date. -
-   -

CALLING SEQUENCE FROM MATLAB: -

- Not available, see MATLAB build-in routines -
-

CALLING SEQUENCE from IDL: -

- Not available, see IDL build-in routines -
-   -

CALLING SEQUENCE from FORTRAN: -

- Result = GET_DOY(Year,Month, Day) -

-
-

-

-

DECY2DATE_AND_TIME -

-

DESRIPTION: -

- Calculate the date and time (yea,month,day of month, - day of year, hour, minute and second and Universal Time) -
-   -

INPUTS: -

- DEC_Y : Decimal year where yyyy.0d0 is January - 1st at 00:00:00 - double -
-   -

OUTPUTS: -

- YEAR: Number year.Year parameters must be valid - values from the civil calendar. Years B.C.E. are represented as negative integers. - Years in the common era are represented as positive integers. In particular, note - that there is no year 0 in the civil calendar. 1 B.C.E. (-1) is followed by 1 C.E. - (1). - long -

- MONTH: Number month (1 = January, ..., 12 = December). - - long -

-

- DAY: Number of day of the month. - long -

-

- DOY: Number of day of year (DOY=1 is for January - 1st) - long -

-

- HOUR, MINUTE and SECOND: Universal time in the - day - long -

-

- UT: Univeral time in seconds - double -
-   -

-

CALLING SEQUENCE FROM MATLAB: -

- Not available, see MATLAB build-in routines -
-

CALLING SEQUENCE from IDL: -

- Not available, see IDL build-in routines -

CALLING SEQUENCE from FORTRAN: -

- CALL DECY2DATE_AND_TIME(Dec_y,Year,Month, Day, doy, - hour,minute,second,UT) -

-
-  

-

-

DATE_AND_TIME2DECY -

-

DESRIPTION: -

- Calculate the decimal year from date and time (yea,month,day - of month, hour, minute and second) -
-   -

INPUTS: -

- YEAR: Number year.Year parameters must be valid - values from the civil calendar. Years B.C.E. are represented as negative integers. - Years in the common era are represented as positive integers. In particular, note - that there is no year 0 in the civil calendar. 1 B.C.E. (-1) is followed by 1 C.E. - (1). - long -

- MONTH: Number month (1 = January, ..., 12 = December). - - long -

-

- DAY: Number of day of the month. - long -

-

- HOUR, MINUTE and SECOND: Universal time in the - day - long -

-
-

OUTPUTS: -

- DEC_Y : Decimal year where yyyy.0d0 is January - 1st at 00:00:00 - double
- -
- -

CALLING SEQUENCE FROM MATLAB: -

- Not available, see MATLAB build-in routines -
-

CALLING SEQUENCE from IDL: -

- Not available, see IDL build-in routines -

CALLING SEQUENCE from FORTRAN: -

- CALL DATE_AND_TIME2DECY(Year,Month,Day,hour,minute,second,Dec_y)
-
-
-  
-

DOY_AND_UT2DATE_AND_TIME -

-

DESRIPTION: -

- Calculate month, day, year from year and day of year
- Calculate time (hour, minute, second) from UT -
-   -

INPUTS: -

- YEAR: Number year.Year parameters must be valid - values from the civil calendar. Years B.C.E. are represented as negative integers. - Years in the common era are represented as positive integers. In particular, note - that there is no year 0 in the civil calendar. 1 B.C.E. (-1) is followed by 1 C.E. - (1). - long -

- DOY: Number of day of year (DOY=1 is for January - 1st) - long -

-

- UT: Universal time in seconds - double -

-
-

OUTPUTS: -

-

- Month : Number month (1 = January, ..., - 12 = December). - long -

-

- Day : Number of day of the month - long -

-

- HOUR, MINUTE and SECOND: Universal - time in the day - long -

- -

-

CALLING SEQUENCE FROM MATLAB: -

- Not available, see MATLAB build-in routines -
-

CALLING SEQUENCE from IDL: -

- Not available, see IDL build-in routines -

CALLING SEQUENCE from FORTRAN: -

- CALL DOY_AND_UT2DATE_AND_TIME(Year,Doy,UT,Month, Day, - hour,minute,second)
-
-
-
-
-

-

-

-

FLY_IN_NASA_AEAP -

-

DESCRIPTION: -

- This function allows one to fly any spacecraft in NASA - AE8 min/max and AP8 min/max models.
- The output can be differential flux or flux within an energy range or integral flux.
- -

INPUTS: -

- ntime: long integer number of time in arrays - (max allowed is GET_IRBEM_NTIME_MAX()) -

- sysaxes: long integer to define which coordinate - system is provided in -
-

-
0: GDZ (alti, lati, East - longi - km,deg.,deg) -
- 1: GEO (cartesian) - Re -
- 2: GSM (cartesian) - Re -
- 3: GSE (cartesian) - Re -
- 4: SM (cartesian) - Re -
- 5: GEI (cartesian) - Re -
- 6: MAG (cartesian) - Re -
- 7: SPH (geo in spherical) - (radial distance, lati, - East longi - Re, deg., deg.)
- 8: RLL  (radial distance, lati, East longi - - Re, deg., deg. - prefered to 7) -
-
-

-

-

- whichm: long integer to select in which NASA - model to fly
- -

-
- - - - - - - - - - -
whichmModel
1=AE8 MIN
2=AE8 MAX
3=AP8 MIN
4=AP8 MAX
-1=AE8 MIN - ESA Interpolation
-2=AE8 MAX - ESA Interpolation
-3=AP8 MIN - ESA Interpolation
-4=AP8 MAX - ESA Interpolation
-
- The ESA Interpolation scheme provides for better flux interpolations at low altitudes.
- See: E. J. Daly, et al., "Problems with models of the radiation belts",
- IEEE Trans. Nucl. Sci, Vol 43, No. 2, Apr. 1996. DOI 10.1109/23.490889
 -
-

-

-

- whatf: long integer to select what flux to compute
- -

-
1=differential flux (MeV-1 cm-2 s-1) - at energy(1,*)
- 2=flux within an ernergy range (MeV-1 cm-2 s-1) - - energy(1,*) to energy(2,*)
- 3=integral flux (cm-2 s-1) at energy(1,*) -
-

-

-

- Nene: long integer number of energies - in array energy (max allowed is 25) -

-

- energy: array(2,25) of double. If whatf=1 or - 3 then energy(2,*) is not considered.
-        Note: if energy is - in MeV then differential flux will be per MeV. -
- -

-

- iyear: array(GET_IRBEM_NTIME_MAX()) of long integer year when positions - are given. Can be a dummy value for the following sysaxes values: 0,1,6,7,8.
- -

-

- idoy: array(GET_IRBEM_NTIME_MAX()) of long integer doy when - positions are given. Can be a dummy value for the following sysaxes values: 0,1,6,7,8.  -

-

- UT: array(GET_IRBEM_NTIME_MAX()) of double, UT in seconds when - positions are given. Can be a dummy value for the following sysaxes values: 0,1,6,7,8  -

-

-

- x1: array(GET_IRBEM_NTIME_MAX()) of double, first coordinate - according to sysaxes. If sysaxes is 0 then altitude has to be in km otherwise use - dimensionless variables (in Re) -

- x2: array(GET_IRBEM_NTIME_MAX()) of double, second coordinate - according to sysaxes. If sysaxes is 0 then latitude has to be in degrees otherwise - use dimensionless variables (in Re) -

-

- x3: array(GET_IRBEM_NTIME_MAX()) of double, third coordinate - according to sysaxes. If sysaxes is 0 then East longitude has to be in degrees otherwise - use dimensionless variables (in Re). -

-
-

OUTPUTS: -

- flux: flux according to selection of whatf for - all times and energies (array(GET_IRBEM_NTIME_MAX(),25) of double) -
-

CALLING SEQUENCE FROM MATLAB: -

- Flux = onera_desp_lib_fly_in_nasa_aeap(sysaxes,whichm,energy,matlabd,x1,x2,x3) -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'fly_in_nasa_aeap_', - ntime,sysaxes,whichm,whatf,Nene,energy,iyear,idoy, UT,x1,x2,x3,flux, /f_value) -

CALLING SEQUENCE from FORTRAN: -

- CALL fly_in_nasa_aeap1(ntime,sysaxes,whichm,whatf,Nene,energy,iyear,idoy, - UT,x1,x2,x3,flux)
-
-
-

-

-

-

GET_AE8_AP8_FLUX -

-

DESCRIPTION: -

-

- This function allows one to compute NASA AE8 min/max - and AP8 min/max flux for any B/Bo, L position.
- The output can be differential flux or flux within an energy range or integral flux.
- -

-

INPUTS: -

-

- ntime: long integer number of points in - arrays (max allowed is GET_IRBEM_NTIME_MAX()) -

-

- whichm: long integer to select in which NASA - model to fly
- -

-
- - - - - - - - - - -
whichmModel
1=AE8 MIN
2=AE8 MAX
3=AP8 MIN
4=AP8 MAX
-1=AE8 MIN - ESA Interpolation
-2=AE8 MAX - ESA Interpolation
-3=AP8 MIN - ESA Interpolation
-4=AP8 MAX - ESA Interpolation
-
- The ESA Interpolation scheme provides for better flux interpolations at low altitudes.
- See: E. J. Daly, et al., "Problems with models of the radiation belts",
- IEEE Trans. Nucl. Sci, Vol 43, No. 2, Apr. 1996. DOI 10.1109/23.490889
 -
-

-

-

- whatf: long integer to select what flux to compute
- -

-
1=differential flux (MeV-1 cm-2 s-1) - at energy(1,*)
- 2=flux within an ernergy range (MeV-1 cm-2 s-1) - - energy(1,*) to energy(2,*)
- 3=integral flux (cm-2 s-1) at energy(1,*) -
-

-

-

- Nene: long integer number of energies - in array energy (max allowed is 25) -

-

- energy: array(2,25) of double. If whatf=1 or - 3 then energy(2,*) is not considered.
-        Note: if energy is - in MeV then differential flux will be per MeV. -
- -

-

- BBo: array(GET_IRBEM_NTIME_MAX()) of double. Provide B/Bequator - for all position where to compute the fluxes. Note that the Jensen and Cain 1960 magnetic - field model must be used for any call to AE8min, AE8max, AP8min and GSFC 1266 (extended - to year 1970) for any call to AP8max.
- -

-

- L: array(GET_IRBEM_NTIME_MAX()) of double. Provide McIlwain - L for all position where to compute the fluxes.  Note that the Jensen - and Cain 1960 magnetic field model must be used for any call to AE8min, AE8max, AP8min - and GSFC 1266 (extended to year 1970) for any call to AP8max.
-

-

-
-

-

OUTPUTS: -

-

- flux: flux according to selection of whatf for - all times and energies (array(GET_IRBEM_NTIME_MAX(),25) of double) -
-

-

CALLING SEQUENCE FROM MATLAB: -

-

- Flux = onera_desp_lib_get_ae8_ap8_flux(whichm,energy,BBo,L) -
-

-

CALLING SEQUENCE from IDL: -

-

- result = call_external(lib_name, 'get_ae8_ap8_flux_idl_', - ntime,whichm,whatf,Nene,energy,BBo,L,,flux, /f_value) -

-

CALLING SEQUENCE from FORTRAN: -

-

- CALL get_ae8_ap8_flux (ntime,whichm,whatf,Nene,energy,BBo,L,flux )
-
-  
-
-

-

- -

FLY_IN_AFRL_CRRES -

-

DESCRIPTION: -

-

- This function allows one to fly any spacecraft in AFRL - CRRESPRO and CRRESELE models.
- The output can be differential flux or flux within an energy range or integral flux. -

-

- Caution: integral flux for electron are from E to  - 5.75 MeV and for proton are from E to 81.3 MeV. -

-

- To run CRRES models you have to set the full path for - the source code directory (where CRRES data files are located).
- -

-

INPUTS: -

- ntime: long integer number of time in arrays - (max allowed is GET_IRBEM_NTIME_MAX()) -

- sysaxes: long integer to define which coordinate - system is provided in -
-

-
0: GDZ (alti, lati, East - longi - km,deg.,deg) -
- 1: GEO (cartesian) - Re -
- 2: GSM (cartesian) - Re -
- 3: GSE (cartesian) - Re -
- 4: SM (cartesian) - Re -
- 5: GEI (cartesian) - Re -
- 6: MAG (cartesian) - Re -
- 7: SPH (geo in spherical) - (radial distance, lati, - East longi - Re, deg., deg.)
- 8: RLL  (radial distance, lati, East longi - - Re, deg., deg. - prefered to 7) -
-
-

-

-

- whichm: long integer to select in which AFRL - CRRES model to fly
- -

-
1=CRRESPRO QUIET
- 2=CRRESPRO ACTIVE
- 3=CRRESELE AVERAGE
- 4=CRRESELE WORST CASE -
-
5=CRRESELE Ap15
-
-

-

-

- whatf: long integer to select what flux to compute
- -

-
1=differential flux (MeV-1 cm-2 s-1) - at energy(1,*)
- 2=flux within an ernergy range (MeV-1 cm-2 s-1) - - energy(1,*) to energy(2,*)
- 3=integral flux (cm-2 s-1) at energy(1,*) -
-

-

- Nene: long integer number of energies in - array energy (max allowed is 25) -

-

-

- energy: array(2,25) of double (MeV). If whatf=1 - or 3 then energy(2,*) is not considered.
- -

-

- iyear: array(GET_IRBEM_NTIME_MAX()) of long integer year when positions - are given. Can be a dummy value for the following sysaxes values: 0,1,6,7,8.
- -

-

- idoy: array(GET_IRBEM_NTIME_MAX()) of long integer doy when - positions are given. Can be a dummy value for the following sysaxes values: 0,1,6,7,8.  -

-

- UT: array(GET_IRBEM_NTIME_MAX()) of double, UT in seconds when - positions are given. Can be a dummy value for the following sysaxes values: 0,1,6,7,8.  -

-

- x1: array(GET_IRBEM_NTIME_MAX()) of double, first coordinate - according to sysaxes. If sysaxes is 0 then altitude has to be in km otherwise use - dimensionless variables (in Re) -

-

- x2: array(GET_IRBEM_NTIME_MAX()) of double, second coordinate - according to sysaxes. If sysaxes is 0 then latitude has to be in degrees otherwise - use dimensionless variables (in Re) -

-

- x3: array(GET_IRBEM_NTIME_MAX()) of double, third coordinate - according to sysaxes. If sysaxes is 0 then longitude has to be in degrees otherwise - use dimensionless variables (in Re). -

-

- Ap15: array(GET_IRBEM_NTIME_MAX()) of double, preceding 15-day - running average of Ap index assuming a one day delay. Array can be set to 0 if whichm - non equal to 5. -

-

- path: byte array where the number of elements - is the length of the string to be converted to byte, provides the path to locate the - files which describe CRRES models. Note that the path should end by a "/" or "\" depending - on your operating system. Before submitting the path it must me converted to byte - array where each element is the ascii code for the corresponding character in the - path.  -

-

- path_len: long integer, provide here the length - of the path string -

-
-

OUTPUTS: -

- flux: flux according to selection of whatf for - all times and energies (array(GET_IRBEM_NTIME_MAX(),25) of double) -
-

CALLING SEQUENCE FROM MATLAB: -

- Flux = onera_desp_lib_fly_in_afrl_crres(sysaxes,whichm,energy,matlabd,x1,x2,x3,Ap15,crres_path) -
-

CALLING SEQUENCE from IDL: -

- result = call_external(lib_name, 'fly_in_afrl_crres_', - ntime,sysaxes,whichm,whatf,Nene,energy,iyear,idoy, UT,x1,x2,x3,Ap15,flux,path,path_len, - /f_value) -

CALLING SEQUENCE from FORTRAN: -

-

- CALL fly_in_afrl_crres1(ntime,sysaxes,whichm,whatf,Nene,energy,iyear,idoy, - UT,x1,x2,x3,Ap15,flux,path,path_len) -

-

-

-

-

-

-

GET_CRRES_FLUX -

-

DESCRIPTION: -

-

- This function allows one to compute AFRL CRRESPRO and - CRRESELE flux for any B/Bo, L position.
- The output can be differential flux or flux within an energy range or integral flux. -

-

- Caution: integral flux for electron are from E to  - 5.75 MeV and for proton are from E to 81.3 MeV. -

-

- To run CRRES models you have to set the full path for - the source code directory (where CRRES data files are located).
- -

-

INPUTS: -

-

- ntime: long integer number of points in - arrays (max allowed is GET_IRBEM_NTIME_MAX()) -

-

-

-

- whichm: long integer to select in which AFRL - CRRES model to fly
- -

-
1=CRRESPRO QUIET
- 2=CRRESPRO ACTIVE
- 3=CRRESELE AVERAGE
- 4=CRRESELE WORST CASE -
-
5=CRRESELE Ap15
-
-

-

-

- whatf: long integer to select what flux to compute
- -

-
1=differential flux (MeV-1 cm-2 s-1) - at energy(1,*)
- 2=flux within an ernergy range (MeV-1 cm-2 s-1) - - energy(1,*) to energy(2,*)
- 3=integral flux (cm-2 s-1) at energy(1,*) -
-

-

-

- Nene: long integer number of energies in - array energy (max allowed is 25) -

-

-

-

- energy: array(2,25) of double (MeV). If whatf=1 - or 3 then energy(2,*) is not considered.
- -

-

- BBo: array(GET_IRBEM_NTIME_MAX()) of double. Provide B/Bequator - for all position where to compute the fluxes. Note that the IGRF1985 magnetic field - model must be used.
- -

-

- L: array(GET_IRBEM_NTIME_MAX()) of double. Provide McIlwain - L for all position where to compute the fluxes.  Note that the IGRF1985 magnetic - field model must be used. -

-

- Ap15: array(GET_IRBEM_NTIME_MAX()) of double, preceding 15-day - running average of Ap index assuming a one day delay. Array can be set to 0 if whichm - non equal to 5. -

-

- path: byte array where the number of elements - is the length of the string to be converted to byte, provides the path to locate the - files which describe CRRES models. Note that the path should end by a "/" or "\" depending - on your operating system. Before submitting the path it must me converted to byte - array where each element is the ascii code for the corresponding character in the - path.  -

-

- path_len: long integer, provide here the length - of the path string -

-

-
-

-

OUTPUTS: -

-

- flux: flux according to selection of whatf for - all times and energies (array(GET_IRBEM_NTIME_MAX(),25) of double) -
-

-

CALLING SEQUENCE FROM MATLAB: -

-

- Flux = onera_desp_lib_get_crres_flux(whichm,energy,BBo,L,Ap15,crres_path) -
-

-

CALLING SEQUENCE from IDL: -

-

- result = call_external(lib_name, 'get_crres_flux_idl_', - ntime,whichm,whatf,Nene,energy,BBo,L,Ap15,flux,path,path_len, /f_value) -

-

CALLING SEQUENCE from FORTRAN: -

-

- CALL get_crres_flux(ntime,whichm,whatf,Nene,energy,BBo,L,Ap15,flux,path,path_len) -

-

-

-

- -

FLY_IN_IGE -

-

DESCRIPTION: -

-

- This function allows one to fly any geostationary spacecraft - in IGE (International Geostationary Electron) models. - The use of the model is limited to geostationary altitude as it is based on LANL-GEO  - bird series (1976 to 2006) and JAXA-DRTS spacecraft (added in IGE2006). Three versions - of the model are provided: -

-
1: known as POLE-V1, it covers electron energies - from 30 keV-1.3 MeV (issued in 2003)
- Published in Boscher D., S. Bourdarie, R. Friedel - and D. Belian, A model for the geostationary electron environment : POLE, IEEE Trans. - Nuc. Sci., 50 (6), 2278-2283, Dec. 2003.
- -
- 2: known as POLE-V2, it covers electron energies from 30 keV-5.2 MeV (issued - in 2005)
- Published in Sicard-Piet A., S. Bourdarie, Boscher - D. and R. Friedel, A model for the geostationary electron environment : POLE - from 30 keV to 5.2 MeV, IEEE Trans. Nuc. Sci., 53 (4), 1844-1850, Aug. 2006.
-
- 3: known as IGE-2006, it covers electron energies from 0.9 keV-5.2 - MeV (issued in 2006)
- Submitted in Sicard-Piet A., S. Bourdarie, Boscher - D., R. Friedel M. Thomsen, T. Goka, H. Matsumoto, H. Koshiishi, A new international - geostationary model: IGE-2006 from 1 keV to 5.2 MeV, JGR-Space Weather, - 2007.
 -
-
-

- Note that POLE stands for Particle-ONERA-LANL-Electrons -

-

- -

-

- The output can be differential flux or flux within an - energy range or integral flux. -

-

- Caution: integral flux for electron are from E to Emax - of the given selected model. So one should be very carrefull when looking at - integral fluxes with POLE-V1 . -
- -

-

INPUTS: -

-

- launch_year: year of spacecraft start of life - in space - long integer -

-

- mission_duration: duration of the mission (number - of years) - long integer -
-

-

- whichm: long integer to select in which IGE - model to fly
- -

-
1=POLE-V1
- 2=POLE-V2
- 3=IGE-2006
-
-
-

-

-

- whatf: long integer to select what flux to compute
- -

-
1=differential flux (MeV-1 cm-2 s-1 sr-1) - at energy(1,*)
- 2=flux within an ernergy range (MeV-1 cm-2 s-1 sr-1) - - energy(1,*) to energy(2,*)
- 3=integral flux (cm-2 s-1 sr-1) at energy(1,*) -
-

-

-

- Nene: long integer number of energies in - array energy (max allowed is 50). If Nene =0 then a default energy grid - is being used. The number of default channels is then returned in Nene.  -

-

-

-

- energy: array(2,50) of double (MeV). If whatf=1 - or 3 then energy(2,*) is not considered. If Nene=0 then the default energies are returned - (in energy(1,1:Nene) in fortran or in energy(0,0:Nene-1)).
- -

-

-

-

OUTPUTS: -

-

- Lower_flux: Lower flux according to selection - of whatf for all energies averaged over entire mission duration - This has to be considered - as a lower envelop to bound expected flux at GEO for any solar cycle (array(50) - of double) -

-

- Mean_flux: Mean flux according to selection of whatf for all energies - averaged over entire mission duration - This spectrum is an averaged expected - flux at GEO for any solar cycle , no margins are included at this point(array(50) - of double) -

-

- Upper_flux: Upper flux according to selection of whatf for all energies - averaged over entire mission duration - This has to be considered as an upper envelop - for expected flux at GEO for any solar cycle, this spectrum can be used for any conservative - approach as margins are included at this point. Note that the margins are enrgy depended - and can be assesed by looking at Upper_flux/Mean_flux (array(50) of double) -

-

-

-

- Note: all flux are expressed in MeV-1 cm-2 s-1 sr-1 for - differential flux or in cm-2 s-1 sr-1 for - integrated flux. To derive omnidirectional flux at GEO one should multiply these - flux values by 4π. -

-

-
-   -

-

CALLING SEQUENCE FROM MATLAB: -

-

- [Lower_flux,Mean_flux,Upper_flux] = onera_desp_lib_fly_in_ige(launch_year,mission_duration,whichm,whatf,energy) -
-

-

CALLING SEQUENCE from IDL: -

-

- result = call_external(lib_name, 'fly_in_ige_', launch_year,mission_duration,whichm,whatf,Nene,energy,Lower_flux,Mean_flux,Upper_flux, - /f_value) -

-

CALLING SEQUENCE from FORTRAN: -

-

- CALL fly_in_ige1(launch_year,mission_duration,whichm,whatf,Nene,energy,Lower_flux,Mean_flux,Upper_flux) -

-

-
-

-

-

-

- -

FLY_IN_MEO_GNSS -

-

DESCRIPTION: -

-

- This function allows one to fly any MEO GNSS type spacecraft - in MEO ONERA models. - The use of the model is limited to GPS altitude (~20000 km - 55� inclination) as it is based on LANL-GPS  - bird series (1990 to 2006). Two versions of the model are provided: -

-
1: known as MEO-V1, it covers electron energies - from 280 keV-1.12 MeV (issued in 2006). Note that in this model there is no solar cycle variations - which is to say that the model should be used for long term studies on the order of a solar cycle duration (i.e. - 11 years). -
-
Published in Sicard-Piet A., S. Bourdarie,D. Boscher, R. Friedel - and T. Cayton, Solar cycle electron environment at GNSS like altitudes, IAC-06-D5.2.04,2006..
-
- 2: known as MEO-V2, it covers electron energies from 280 keV-2.24 MeV (issued - in 2007) -
-
Not published yet. -
-
-
-

- The output can be differential flux or flux within an - energy range or integral flux. -

-
-

INPUTS: -

-

- launch_year: year of spacecraft start of life - in space - long integer -

-

- mission_duration: duration of the mission (number - of years) - long integer -
-

-

- whichm: long integer to select in which MEO - model to fly
- -

-
- 1=MEO-V1
- 2=MEO-V2
-
-
-

-

-

- whatf: long integer to select what flux to compute
- -

-
1=differential flux (MeV-1 cm-2 s-1 sr-1) - at energy(1,*)
- 2=flux within an ernergy range (MeV-1 cm-2 s-1 sr-1) - - energy(1,*) to energy(2,*)
- 3=integral flux (cm-2 s-1 sr-1) at energy(1,*) -
-

-

-

- Nene: long integer number of energies in - array energy (max allowed is 50). If Nene =0 then a default energy grid - is being used. The number of default channels is then returned in Nene.  -

-

-

-

- energy: array(2,50) of double (MeV). If whatf=1 - or 3 then energy(2,*) is not considered. If Nene=0 then the default energies are returned - (in energy(1,1:Nene) in fortran or in energy(0,0:Nene-1)).
- -

-

-

-

OUTPUTS: -

-

- Lower_flux: Lower flux according to selection - of whatf for all energies averaged over entire mission duration - This has to be considered - as a lower envelop to bound expected flux at MEO-GNSS for any solar cycle (array(50) - of double) -

-

- Mean_flux: Mean flux according to selection of whatf for all energies - averaged over entire mission duration - This spectrum is an averaged expected - flux at MEO-GNSS for any solar cycle , no margins are included at this point(array(50) - of double) -

-

- Upper_flux: Upper flux according to selection of whatf for all energies - averaged over entire mission duration - This has to be considered as an upper envelop - for expected flux at MEO-GNSS for any solar cycle, this spectrum can be used for any conservative - approach as margins are included at this point. Note that the margins are enrgy depended - and can be assesed by looking at Upper_flux/Mean_flux (array(50) of double) -

-

-

-

- Note: all flux are expressed in MeV-1 cm-2 s-1 sr-1 for - differential flux or in cm-2 s-1 sr-1 for - integrated flux. To derive omnidirectional flux at MEO-GNSS one should multiply these - flux values by 4π. -

-

-
-   -

-

CALLING SEQUENCE FROM MATLAB: -

-

- [Lower_flux,Mean_flux,Upper_flux] = onera_desp_lib_fly_in_meo_gnss(launch_year,mission_duration,whichm,energy) -
-

-

CALLING SEQUENCE from IDL: -

-

- result = call_external(lib_name, 'fly_in_meo_gnss_', launch_year,mission_duration,whichm,whatf,Nene,energy,Lower_flux,Mean_flux,Upper_flux, - /f_value) -

-

CALLING SEQUENCE from FORTRAN: -

-

- CALL fly_in_meo_gnss1(launch_year,mission_duration,whichm,whatf,Nene,energy,Lower_flux,Mean_flux,Upper_flux) -

-

-
-

-

-

-

-

MSIS86 -

-

DESCRIPTION: -

-

- The Mass-Spectrometer-Incoherent-Scatter-1986 (MSIS-86) - neutral atmosphere model describes the neutral temperature and the densities of He, - O, N2, O2, Ar, H, and N. The MSIS model is based on the extensive data compilation - and analysis work of A. E. Hedin and his collaborators [A. E. Hedin et al., J. Geophys. - Res. 82, 2139-2156, 1977; A. E. Hedin, J. Geophys. Res. 88, 10170- 10188, 1983; A. - E. Hedin, J. Geophys. Res. 92, 4649, 1987]. MSIS-86 constitutes the upper part of - the COSPAR International Reference Atmosphere (CIRA-86). -

-

- Data sources for the present model include temperature - and density measurements from several rockets, satellites (OGO-6, San Marco 3, Aeros-A, - AE-C, AE-D, AE-E, ESRO 4 and DE-2) and incoherent scatter radars (Millstone Hill, - St. Santin, Arecibo, Jicamarca, and Malvern). Since the MSIS-83 model, terms were - added or changed to better represent seasonal variations in the polar regions under - both quiet and magnetically disturbed conditions and local time variations in the - magnetic activity effect. In addition a new species, atomic nitrogen, was added to - the list of species covered by the model. -

-

INPUTS: -

-

- Ntime: long integer number of time in arrays - (max allowed is GET_IRBEM_NTIME_MAX()) -

-

- WhichAp: long integer to select the kind - of Ap input:
-

-

-

-

-

-

-

-

-

-

-

-

-

-
1=Only daily Ap magnetic index is provided in Ap array - (i.e. 1st element)
- 2=All fields in Ap array are provided (i.e. the 7th elements)
-
-

-

-

- DOY: array(GET_IRBEM_NTIME_MAX()) of long integer, Number of - day of year (DOY=1 is for January 1st) -

-

- UT: array(GET_IRBEM_NTIME_MAX()) of double, UT in - seconds when positions are given.. -

-

- Alt: array(GET_IRBEM_NTIME_MAX()) of double, Altitude - in km (greater than 85 km). -

-

- Lat: array(GET_IRBEM_NTIME_MAX()) of double, Geodetic - latitude (Deg.) -

-

- Long: array(GET_IRBEM_NTIME_MAX()) of double, Geodetic - longitude (Deg.) -

-

- F107A: array(GET_IRBEM_NTIME_MAX()) of double, 3 month - average of F10.7 flux. -

-

- F107: array(GET_IRBEM_NTIME_MAX()) of double, daily - F10.7 flux for previous day. -

-

- Ap: array(7,GET_IRBEM_NTIME_MAX()) of double where:
- -

-
1st element=Daily Ap
- 2nd element=3 hours Ap index for current time
- 3rd element=3 hours Ap index for 3 hours before current time -
- 4th element=3 hours Ap index for 6 hours before current time
- 5th element=3 hours Ap index for 9 hours before current time
- 6th element=Average of eight 3 hours Ap indices from 12 to 33 hours prior to current - time
- 7th element=Average of eight 3 hours Ap indices from 36 to 59 hours prior to current - time -
-

-

-

OUTPUTS: -

-

- Dens: array(8,GET_IRBEM_NTIME_MAX()) of double where:
- -

-
Dens(1st element,*)=He number density (cm-3) -
-
Dens(2nd element,*)=O number density (cm-3)
- Dens(3rd element,*)=N2 number density (cm-3)
- Dens(4th element,*)=O2 number density (cm-3)
- Dens(5th element,*)=AR number density (cm-3)
- Dens(6th element,*)=Total mass density (g/cm-3)
- Dens(7th element,*)=H number density (cm-3)
- Dens(8th element,*)=N number density (cm-3) -
-

- Temp: array(2,GET_IRBEM_NTIME_MAX()) of double where:
- -

-
Temp(1st element,*)=Exospheric temperature (K) -
-
Temp(2nd element,*)=Temperature at alt (K)  -
-

-

-   -

CALLING SEQUENCE FROM MATLAB: -

-

- out = onera_desp_lib_msis('msis86',date,X,sysaxes,F107A,F107,Ap) -
-

-

CALLING SEQUENCE from IDL: -

-

- result = call_external(lib_name, 'msis86_idl_', ntime,whichAp,DOY,UT,Alt,Lat,Lon,F107A,F107,Ap,Dens,Temp, - /f_value) -

-

CALLING SEQUENCE from FORTRAN: -

-

- CALL msis86(ntime,whichAp,DOY,UT,Alt,Lat,Lon,F107A,F107,Ap,Dens,Temp) -

-

-
-

-

-

-

-

MSISE90 -

-

DESCRIPTION: -

-

- The MSISE model describes the neutral temperature and - densities in Earth's atmosphere from ground to thermospheric heights. Below 72.5 km - the model is primarily based on the MAP Handbook (Labitzke et al., 1985) tabulation - of zonal average temperature and pressure by Barnett and Corney, which was also used - for the CIRA-86. Below 20 km these data were supplemented with averages from the National - Meteorological Center (NMC). In addition, pitot tube, falling sphere, and grenade - sounder rocket measurements from 1947 to 1972 were taken into consideration. Above - 72.5 km MSISE-90 is essentially a revised MSIS-86 model taking into account data derived - from space shuttle flights and newer incoherent scatter results. For someone interested - only in the thermosphere (above 120 km), the author recommends the MSIS-86 model. - MSISE is also not the model of preference for specialized tropospheric work. It is - rather for studies that reach across several atmospheric boundaries. -

-

-

-

INPUTS: -

-

- Ntime: long integer number of time in arrays - (max allowed is GET_IRBEM_NTIME_MAX()) -

-

- WhichAp: long integer to select the kind - of Ap input:
-

-

-

-

-

-

-

-

-

-
1=Only daily Ap magnetic index is provided in Ap array - (i.e. 1st element)
- 2=All fields in Ap array are provided (i.e. the 7th elements)
-
-

-

-

- DOY: array(GET_IRBEM_NTIME_MAX()) of long integer, Number of - day of year (DOY=1 is for January 1st) -

-

- UT: array(GET_IRBEM_NTIME_MAX()) of double, UT in - seconds when positions are given.. -

-

- Alt: array(GET_IRBEM_NTIME_MAX()) of double, Altitude - (km). -

-

- Lat: array(GET_IRBEM_NTIME_MAX()) of double, Geodetic - latitude (Deg.) -

-

- Long: array(GET_IRBEM_NTIME_MAX()) of double, Geodetic - longitude (Deg.) -

-

- F107A: array(GET_IRBEM_NTIME_MAX()) of double, 3 month - average of F10.7 flux. -

-

- F107: array(GET_IRBEM_NTIME_MAX()) of double, daily - F10.7 flux for previous day. -

-

- Ap: array(7,GET_IRBEM_NTIME_MAX()) of double where:
- -

-
1st element=Daily Ap
- 2nd element=3 hours Ap index for current time
- 3rd element=3 hours Ap index for 3 hours before current time -
- 4th element=3 hours Ap index for 6 hours before current time
- 5th element=3 hours Ap index for 9 hours before current time
- 6th element=Average of eight 3 hours Ap indices from 12 to 33 hours prior to current - time
- 7th element=Average of eight 3 hours Ap indices from 36 to 59 hours prior to current - time -
-

-

-

-

-

- -

-

-

- OUTPUTS: -

- Dens: array(8,GET_IRBEM_NTIME_MAX()) of double where:
- -

-
Dens(1st element,*)=He number density (cm-3) -
-
Dens(2nd element,*)=O number density (cm-3)
- Dens(3rd element,*)=N2 number density (cm-3)
- Dens(4th element,*)=O2 number density (cm-3)
- Dens(5th element,*)=AR number density (cm-3)
- Dens(6th element,*)=Total mass density (g/cm-3)
- Dens(7th element,*)=H number density (cm-3)
- Dens(8th element,*)=N number density (cm-3) -
-

- Temp: array(2,GET_IRBEM_NTIME_MAX()) of double where:
- -

-
Temp(1st element,*)=Exospheric temperature (K) -
-
Temp(2nd element,*)=Temperature at alt (K)  -
-

-

-   -

CALLING SEQUENCE FROM MATLAB: -

-

- out = onera_desp_lib_msis('msise90',date,X,sysaxes,F107A,F107,Ap) -
-

-

CALLING SEQUENCE from IDL: -

-

- result = call_external(lib_name, 'msise90_idl_', ntime,whichAp,DOY,UT,Alt,Lat,Lon,F107A,F107,Ap,Dens,Temp, - /f_value) -

-

CALLING SEQUENCE from FORTRAN: -

-

- CALL msise90(ntime,whichAp,DOY,UT,Alt,Lat,Lon,F107A,F107,Ap,Dens,Temp) -

-

-
-

-

-

-

-

NRLMSIS00 -

-

DESCRIPTION: -

-

- The NRLMSIS-00 empirical atmosphere model was developed - by Mike Picone, Alan Hedin, and Doug Drob based on the MSISE90 model. The main differences - to MSISE90 are noted in the comments at the top of the computer code. They involve - (1) the extensive use of drag and accelerometer data on total mass density, (2) the - addition of a component to the total mass density that accounts for possibly significant - contributions of O+ and hot oxygen at altitudes above 500 km, and (3) the inclusion - of the SMM UV occultation data on [O2]. The MSISE90 model describes the neutral temperature - and densities in Earth's atmosphere from ground to thermospheric heights. Below 72.5 - km the model is primarily based on the MAP Handbook (Labitzke et al., 1985) tabulation - of zonal average temperature and pressure by Barnett and Corney, which was also used - for the CIRA-86. Below 20 km these data were supplemented with averages from the National - Meteorological Center (NMC). In addition, pitot tube, falling sphere, and grenade - sounder rocket measurements from 1947 to 1972 were taken into consideration. Above - 72.5 km MSISE-90 is essentially a revised MSIS-86 model taking into account data derived - from space shuttle flights and newer incoherent scatter results. For someone interested - only in the thermosphere (above 120 km), the author recommends the MSIS-86 model. - MSISE is also not the model of preference for specialized tropospheric work. It is - rather for studies that reach across several atmospheric boundaries. -

-

INPUTS: -

-

- Ntime: long integer number of time in arrays - (max allowed is GET_IRBEM_NTIME_MAX()) -

-

- WhichAp: long integer to select the kind - of Ap input:
 -

-

-

-

-

-

-

-

-

-

-

-

-

-

-

-
1=Only daily Ap magnetic index is provided in Ap array - (i.e. 1st element)
- 2=All fields in Ap array are provided (i.e. the 7th elements)
 -
-

-

-

- DOY: array(GET_IRBEM_NTIME_MAX()) of long integer, Number of - day of year (DOY=1 is for January 1st) -

-

- UT: array(GET_IRBEM_NTIME_MAX()) of double, UT in - seconds when positions are given.. -

-

- Alt: array(GET_IRBEM_NTIME_MAX()) of double, Altitude - in km (greater than 85 km). -

-

- Lat: array(GET_IRBEM_NTIME_MAX()) of double, Geodetic - latitude (Deg.) -

-

- Long: array(GET_IRBEM_NTIME_MAX()) of double, Geodetic - longitude (Deg.) -

-

- F107A: array(GET_IRBEM_NTIME_MAX()) of double, 3 month - average of F10.7 flux. -

-

- F107: array(GET_IRBEM_NTIME_MAX()) of double, daily - F10.7 flux for previous day. -

-

- Ap: array(7,GET_IRBEM_NTIME_MAX()) of double where:
- -

-
1st element=Daily Ap
- 2nd element=3 hours Ap index for current time
- 3rd element=3 hours Ap index for 3 hours before current time -
- 4th element=3 hours Ap index for 6 hours before current time
- 5th element=3 hours Ap index for 9 hours before current time
- 6th element=Average of eight 3 hours Ap indices from 12 to 33 hours prior to current - time
- 7th element=Average of eight 3 hours Ap indices from 36 to 59 hours prior to current - time -
-

-

-

-

-

-

-

-

- OUTPUTS: -

- Dens: array(9,GET_IRBEM_NTIME_MAX()) of double where:
- -

-
Dens(1st element,*)=He number density (cm-3) -
-
Dens(2nd element,*)=O number density (cm-3)
- Dens(3rd element,*)=N2 number density (cm-3)
- Dens(4th element,*)=O2 number density (cm-3)
- Dens(5th element,*)=AR number density (cm-3)
- Dens(6th element,*)=Total mass density (g/cm-3)
- Dens(7th element,*)=H number density (cm-3)
- Dens(8th element,*)=N number density (cm-3) -
- Dens(9th element,*)=Anomalous oxygen number density (cm-3) -
-

- Temp: array(2,GET_IRBEM_NTIME_MAX()) of double where:
- -

-
Temp(1st element,*)=Exospheric temperature (K) -
-
Temp(2nd element,*)=Temperature at alt (K)  -
-

-

-   -

CALLING SEQUENCE FROM MATLAB: -

-

- out = onera_desp_lib_msis('nrlmsise00',date,X,sysaxes,F107A,F107,Ap) 
-

-

CALLING SEQUENCE from IDL: -

-

- result = call_external(lib_name, 'nrlmsise00_idl_', - ntime,whichAp,DOY,UT,Alt,Lat,Lon,F107A,F107,Ap,Dens,Temp, /f_value) -

-

CALLING SEQUENCE from FORTRAN: -

-

- CALL nrlmsise00(ntime,whichAp,DOY,UT,Alt,Lat,Lon,F107A,F107,Ap,Dens,Temp) -

-

-
-

-

-

-

-

SGP4_TLE -

-

DESCRIPTION: -

-

- SGP4 stands for Simplified General Perturbation -4 and - consists in an orbit propagator. This function allows one to propagate NORAD two lines - elements (TLE sets can be found at http://celestrak.com/). - More about SGP4 can be found at: http://celestrak.com/NORAD/documentation/spacetrk.pdf and - at http://www.centerforspace.com/downloads/files/pubs/AIAA - 2006-6753 Revisiting Spacetrack Report 3.pdf -

-

- Important notice: those who are running the library on Unix or linux system have to - convert TLE files from NORAD from DOS to UNIX using the command : dos2unix file.tle - newfile.tle . Also be aware that some TLE files contains random errors, like - elements from another satellite, repeated elements, ... there are no specific filters - implemented in the SGP4 function. -

-

- For those who are familiar with SGP4 code, be aware for one difference between orginal - SGP4 code and the one provided here: input start and stop time and time step are not - in minutes but in seconds. This was chosen for convenience. -

-

- -

-

INPUTS: -

-

- runtype: long integer to select in - which mode SGP4_TLE will run  -

-
0: defines start and - stop time to propagate each TLE according to input file 
- 1: propagates each TLE according to user start - and stop time  -
-
-

- startsfe: double giving start time in seconds - from date provided in each TLE. This number can be negative. Note that this - value is not use if runtype is equal to 0. -

-

- stopsfe: double giving stop time in seconds from date provided in - each TLE. This number can be negative. Note that this value is not use if runtype - is equal to 0.
-
- deltasec: double giving step time in seconds to propagateTLE. -

-

-

-

- InFileByte: byte array where the number of elements - is the length of the string to be converted to byte, provides the path and name to - locate the input TLE to be propagated. Before submitting the path it must - me converted to byte array where each element is the ascii code for the corresponding - character in the path.  -

-

- strlenIn: long integer providing the length of - InFileByte string -

-

- OutFileByte: byte array where the number of elements - is the length of the string to be converted to byte, provides the path and name to - locate the output file. Before submitting the path it must me converted - to byte array where each element is the ascii code for the corresponding character - in the path.  -

-

- strlenOut: long integer providing here the length - of OutFileByte string 
-   -

-

OUTPUTS: -

-

- None: They are provided in OutFileByte. - This file is composed of 6 columns: 
-

-
1: date (dd/mm/yyyy) 
- 2: time (hh:mm:ss) -
-
3: decimal year -
-
4: altitude (km) -
-
5: latitude (deg) -
-
6: East longitude (deg)  -
-
-

-

-

CALLING SEQUENCE FROM MATLAB: -

-

- The Matlab wrapper handles calculation of runtype strlenIn, OutfileByte, strlenOut. - OutfileByte and strlenOut will be set appropriately for a temporary file (onera_desp_lib_sgp4_tle.tmp - or onera_desp_lib_sgp4_tle.tmp.####). The wrapper reads the library routine's output - from the temporary file and passes it back as a Matlab structure. The temporary file - is deleted, so the Matlab structure is the only result of a successful call to sgp4_tle. - In order to avoid a memory overflow for very long TLE runs, it is possible to leave - the output in a text file (as in the FORTRAN call): the syntax is then onera_desp_lib_sgp4_tle(InFile,OutFile) -

-

- pos = onera_desp_lib_sgp4_tle(InFileByte) %implies runtype=0
-

-

- pos = onera_desp_lib_sgp4_tle(startsfe,stopsfe,deltasec,InFileByte) %implies runtype=1
-

-

CALLING SEQUENCE from IDL: -

-

- result = call_external(lib_name, 'sgp4_tle_', runtype,startsfe,stopsfe,deltasec,InFileByte,strlenIn,OutFileByte,strlenOut, - /f_value) -

-

CALLING SEQUENCE from FORTRAN: -

-

- CALL sgp4_tle1(runtype,startsfe,stopsfe,deltasec,InFileByte,strlenIn,OutFileByte,strlenOut)
-
-  

-

-

SGP4_ELE -

-

DESCRIPTION: -

-

- SGP4 stands for Simplified General Perturbation -4 and - consists in an orbit propagator. This function allows one to produce orbit coordinates - from different types of orbital elements... More about SGP4 can be found at: http://celestrak.com/NORAD/documentation/spacetrk.pdf and - at http://www.centerforspace.com/downloads/files/pubs/AIAA - 2006-6753 Revisiting Spacetrack Report 3.pdf -

-

- For those who are familiar with SGP4 code, be aware for one difference between orginal - SGP4 code and the one provided here: input start and stop time and time step are not - in minutes but in seconds. This was chosen for convenience. -

-

-

-

- -

-

INPUTS: -

-

- sysaxesOUT: long integer to define which coordinate - system is provided out -
-

-
0: GDZ (alti, lati, East - longi - km,deg.,deg) -
- 1: GEO (cartesian) - Re -
- 2: GSM (cartesian) - Re -
- 3: GSE (cartesian) - Re -
- 4: SM (cartesian) - Re -
- 5: GEI (cartesian) - Re -
- 6: MAG (cartesian) - Re -
- 7: SPH (geo in spherical) - (radial distance, lati, - East longi - Re, deg., deg.)
- 8: RLL  (radial distance, lati, East longi - - Re, deg., deg. - prefered to 7) -
-
-

- year: long integer giving start - year of start date -

-

- month: long integer giving start - month of start date -

-

- day: long integer giving start - day of month of start date. -

-

- hour: long integer giving start hour - of start time. -

-

- minute: long integer giving start minute - of start time. -

-

- sec: double giving start seconds - of start time. -

-

- e1: double see detailed definition - according to options array. -

-

- e2: double see detailed definition - according to options array. -

-

- e2: double see detailed definition - according to options array. -

-

- e4: double see detailed definition - according to options array. -

-

- e5: double see detailed definition - according to options array. -

-

- e6: double see detailed definition - according to options array. -

-

- options: array(5) of long integer to define which type - of element is provided in -
- Case options(1st element) - of: -
-
-

-
1: ONERA type elements:  -
-
e1 = Inclination - deg -
- e2 = geocentric altitude of perigee - km -
- e3 = geocentric altitude of apogee - km -
- e4 = longitude of the ascending node - deg -
- Case options(2nd element) of: -
-
1: e5 = argument - of perigee - deg -
- 2: e5 = longitude of perigee - deg -
-
- Case options(3rd element) of: -
-
1: e6 = time since - perigee passage - sec -
- 2: e6 = true anomaly at epoch - deg -
- 3: e6 = argument of latitude at epoch - deg -
- 4: e6 = true longitude at epoch - deg -
- 5: e6 = mean anomaly at epoch - deg -
-
-
-
- 2: Classical type elements: 
-
e1 = semimajor axis - - Re -
- e2 = eccentricity -
- e3 = inclination - deg -
- e4 = longitude of ascending node - deg -
- Case options(2nd element) of: -
-
1: e5 = argument - of perigee - deg -
- 2: e5 = longitude of perigee - deg -
-
- Case options(3rd element) of: -
-
1: e6 = time since - perigee passage - sec -
- 2: e6 = true anomaly at epoch - deg -
- 3: e6 = argument of latitude at epoch - deg -
- 4: e6 = true longitude at epoch - deg -
- 5: e6 = mean anomaly at epoch - deg -
-
-
-
- 3: RV type elements: 
-
e1 = xGEI - km -
- e2 = yGEI - km -
- e3 = zGEI - km -
- e4 = VxGEI - km/s -
- e5 = VyGEI - km/s -
- e6 = VzGEI - km/s -
-
-
- 4: SOLAR type elements: 
-
e1 = inclination - deg -
- e2 = geocentric altitude of perigee - km -
- e3 = geocentric altitude of apogee - km -
- e4 = local time of apogee - hours -
- e5 = local time of maximum inclination - hours -
- Case options(3rd element) of: -
-
1: e6 = time since - perigee passage - sec -
- 2: e6 = true anomaly at epoch - deg -
- 3: e6 = argument of latitude at epoch - deg -
- 4: e6 = true longitude at epoch - deg -
- 5: e6 = mean anomaly at epoch - deg -
-
-
-
- 5: MEAN type elements:  -
-
e1 = mean motion - rev/day -
- e2 = eccentricity -
- e3 = inclination - deg -
- e4 = longitude of the ascending node - deg -
- Case options(2nd element) of: -
-
1: e5 = argument - of perigee - deg -
- 2: e5 = longitude of perigee - deg -
-
- Case options(3rd element) of: -
-
1: e6 = time since - perigee passage - sec -
- 2: e6 = true anomaly at epoch - deg -
- 3: e6 = argument of latitude at epoch - deg -
- 4: e6 = true longitude at epoch - deg -
- 5: e6 = mean anomaly at epoch - deg -
-
-
-
-
-

- startsfe: double giving start time in seconds - from date provided before. This number can be negative. -

-

- stopsfe: double giving stop time in - seconds from date provided before. This number can be negative. -
-
- deltasec: double giving step time - in seconds to produce orbit outputs. -

-

-

-

-

-

OUTPUTS: -

-

- OUTyear: array of long integer(GET_IRBEM_NTIME_MAX()) giving - output year for each orbital locations -
-

-

- OUTdoy: array of long integer(GET_IRBEM_NTIME_MAX()) giving - output day of year for each orbital locations -
-

-

- UT: array of double(GET_IRBEM_NTIME_MAX()) giving - output UT (seconds) for each orbital locations -

-

- X1: array of double(GET_IRBEM_NTIME_MAX()) giving - first coordinate of orbit according to sysaxes -
-

-

- X2: array of double(GET_IRBEM_NTIME_MAX()) giving second - coordinate of orbit according to sysaxes -

-

- X3: array of double(GET_IRBEM_NTIME_MAX()) giving third - coordinate of orbit according to sysaxes -
-

-

-

-

CALLING SEQUENCE FROM MATLAB: -

-

- pos = onera_desp_lib_sgp4_ele([e1,e2,e3,e4,e5,e6],startdate,enddate,deltasec,sysaxesOUT) 
-

-

CALLING SEQUENCE from IDL: -

-

- result = call_external(lib_name, 'sgp4_ele_', sysaxesOUT,year,month,day,hour,minute,sec, - e1,e2,e3,e4,e5,e6,options,startsfe,stopsfe,deltasec,OUTyear,OUTdoy,UT,X1,X2,X3, /f_value) -

-

CALLING SEQUENCE from FORTRAN: -

-

- CALL sgp4_ele1(sysaxesOUT,year,month,day,hour,minute,sec, - e1,e2,e3,e4,e5,e6,options,startsfe,stopsfe,deltasec,OUTyear,OUTdoy,UT,X1,X2,X3)
-
- -
-

-  
-

RV2COE -

-

DESCRIPTION: -

-

- This function finds the classical orbital elements given - the Geocentric Equatorial Position and Velocity vectors. It comes from SGP4 distribution. - SGP4 stands for Simplified General Perturbation -4 and consists in an orbit propagator. - More about SGP4 can be found at: http://celestrak.com/NORAD/documentation/spacetrk.pdf and - at http://www.centerforspace.com/downloads/files/pubs/AIAA - 2006-6753 Revisiting Spacetrack Report 3.pdf -

-

-

-

- -

-

INPUTS: -

-

- R: array(3) of double. Position vector in GEI - (km)  -

-

- V: array(3) of double. Velocity vector in - GEI (km/s). -

-

OUTPUTS: -

-

- P: double. SemiLatus rectum (km) 
-

-

- A: double. Semimajor axis (km)  -

-

- Ecc: double. Eccentricity 
-

-

- Incl: double. Inclination (rad)  -

-

- Omega: double. Longitude of ascending - node (rad) -

-

- Argp: double. Argument of perigee (rad)  -

-

- Nu: double. True anomaly (rad)  -

-

- M: double. Mean anomaly (rad)  -

-

- ArgLat: double. Argument of latitude - (rad) -

-

- LamTrue: double. True longitude (rad)  -

-

- LonPer: double. Longitude of Periapsis - (rad) 
-

-

-

-

CALLING SEQUENCE FROM MATLAB: -

-

- elements=onera_desp_lib_rv2coe(R,V) 
-

-

CALLING SEQUENCE from IDL: -

-

- result = call_external(lib_name, 'rv2coe_idl_', R,V,P,A,Ecc,Incl,Omega,Argp,Nu,M,ArgLat,LamTrue,LonPer, - /f_value) -

-

CALLING SEQUENCE from FORTRAN: -

-

- CALL rv2coe(R,V,P,A,Ecc,Incl,Omega,Argp,Nu,M,ArgLat,LamTrue,LonPer)
-
- -
-

-   -
-
-

-

- -

-
-

-

-

IRBEM_FORTRAN_VERSION -

-

DESCRIPTION: -

- Provides the repository version number of the fortran source code. -
-   -

INPUTS: -

- NONE -

OUTPUTS: -

- VERSN Repository version number (long integer). -
-   -

CALLING SEQUENCE FROM MATLAB: -

- VERSN = onera_desp_lib_fortran_version -
-

CALLING SEQUENCE FROM IDL: -

- result = call_external(lib_name, 'irbem_fortran_version_',versn, /f_value) -
-

CALLING SEQUENCE from FORTRAN: -

- call IRBEM_FORTRAN_VERSION1(VERSN) -

-
-

-

-

IRBEM_FORTRAN_RELEASE -

-

DESCRIPTION: -

- Provides the repository release tag of the fortran source code. -
-   -

INPUTS: -

- NONE -

OUTPUTS: -

- RLS Repository release tag (character(80)). -
-   -

CALLING SEQUENCE FROM MATLAB: -

- RLS = onera_desp_lib_fortran_release -
-

CALLING SEQUENCE FROM IDL: -

- result = call_external(lib_name, 'irbem_fortran_release_', rls, /f_value)
- Tip: In IDL, string arguments should be defined as byte arrays, i.e.: -    rls = BYTARR(80) -
-

CALLING SEQUENCE from FORTRAN: -

- call IRBEM_FORTRAN_RELEASE1(RLS) -

-
-

-

-

GET_IGRF_VERSION -

-

DESCRIPTION: -

- Returns the version number of the IGRF model. -
-   -

INPUTS: -

- NONE -

OUTPUTS: -

- IGRF_VERSION IGRF version number (long integer). -
-   -

CALLING SEQUENCE FROM MATLAB: -

- ntime_max = onera_desp_lib_igrf_version -
-

CALLING SEQUENCE FROM IDL: -

- result = call_external(lib_name, 'igrf_version_idl_',igrf_version, /f_value) -
-

CALLING SEQUENCE from FORTRAN: -

- call GET_IGRF_VERION_(igrf_version) -
-

-
-

-

-

GET_IRBEM_NTIME_MAX -

-

DESCRIPTION: -

- Returns size of time dimension in preallocated fortran arrays. -
-   -

INPUTS: -

- NONE -

OUTPUTS: -

- NTIME_MAXTime dimension size (long integer). -
-   -

CALLING SEQUENCE FROM MATLAB: -

- ntime_max = onera_desp_lib_ntime_max -
-

CALLING SEQUENCE FROM IDL: -

- result = call_external(lib_name, 'get_irbem_ntime_max_',ntime_max, /f_value) -
-

CALLING SEQUENCE from FORTRAN: -

- call GET_IRBEM_NTIME_MAX1(ntime_max1) -
-  
-

SHIELDOSE2 -

-

DESCRIPTION: -

-

- SHIELDOSE2 [Seltzer, 1994] is a computer code for - space-shielding radiation dose calculations. It determines the absorbed dose as a - function of depth in aluminium shielding material of spacecraft, given the electron - and proton fluences encountered in orbit. The code makes use of precalculated, - mono-energetic depth-dose data for an isotropic, broad-beam fluence of radiation - incident on uniform aluminium plane media. Such data are particularly suitable for - routine dose predictions in situations where the geometrical and compositional - complexities of the spacecraft are not known. Furthermore, the restriction to these - rather simple geometries has allowed for the development of accurate electron and - electron-bremsstrahlung data sets based on detailed transport calculations rather - than on more approximate methods.
- SHIELDOSE2 calculates, for arbitrary proton and electron incident spectra, - the dose absorbed in small volumes of different detector materials for the - following aluminium shield geometries: -

    -
  1. - in a semi-infinite plane medium, as a function of depth; irradiation is from one side only (the assumed infinite backing effectively insures this). -
    2. -
  2. - at the transmission surface of a plane slab, as a function of slab thickness; irradiation is from one side only. -
    3. -
  3. - at the centre of a solid sphere, as a function of sphere radius; irradiation is from all directions.

    -
    4. -
-

-

-

- -

-

INPUTS: -

-

- IDET: long integer to set the index of the detector type: -

    -
  1. Al detector
    2. -
  2. Graphite detector
    3. -
  3. Si detector
    4. -
  4. Air detector
    5. -
  5. Bone detector
    6. -
  6. Calcium Fluoride detector
    7. -
  7. Gallium Arsenide detector
    8. -
  8. Lithium Fluoride detector
    9. -
  9. Silicon Dioxide detector
    10. -
  10. Tissue detector
    11. -
  11. Water detector
    12. -
- - INUC: long integer to indicate the nuclear interaction to account for: -
    -
  1. No nuclear attenuation for protons in Al
    2. -
  2. Nuclear attenuation, local charged-secondary energy deposition
    3. -
  3. Nuclear attenuation, local charged-secondary energy deposition, and approx exponential distribution of neutron dose
    4. -
- - IMAX: long integer to set the number of shielding depth (max allowed=71). It is recommended to set this number close to maximum allowed value to compute accurate doses in semi-infinite aluminium medium and at center of aluminium spheres. - -

- IUNT: long integer to set the shielding depth unit -
    -
  1. Mils
    2. -
  2. g/cm2
    3. -
  3. mm
    4. -
- - Zin: double array(71) of thickness in unit of IUNT. Below is provided a reasonable thickness array in g/cm2 with IMAX=70
- data Zin /1.000E-06,2.000E-06,5.000E-06,1.000E-05,2.000E-05,5.000E-05,1.000E-04,2.000E-04,&
- 5.000E-04,1.000E-03,1.000E-01,2.000E-01,5.000E-01,7.000E-01,1.000E+00,1.250E+00,&
- 1.500E+00,1.750E+00,2.000E+00,2.500E+00,3.000E+00,3.500E+00,4.000E+00,4.500E+00,&
- 5.000E+00,6.000E+00,7.000E+00,8.000E+00,9.000E+00,1.000E+01,1.100E+01,1.200E+01,&
- 1.300E+01,1.400E+01,1.500E+01,1.600E+01,1.700E+01,1.800E+01,1.900E+01,2.000E+01,&
- 2.100E+01,2.200E+01,2.300E+01,2.400E+01,2.500E+01,2.600E+01,2.700E+01,2.800E+01,&
- 2.900E+01,3.000E+01,3.100E+01,3.200E+01,3.300E+01,3.400E+01,3.500E+01,3.600E+01,&
- 3.700E+01,3.800E+01,3.900E+01,4.000E+01,4.100E+01,4.200E+01,4.300E+01,4.400E+01,&
- 4.500E+01,4.600E+01,4.700E+01,4.800E+01,4.900E+01,5.000E+01,0.000E+00/ - -

- EminS: min energy of solar protons spectrum (double) [MeV] - -

- EmaxS: max energy of solar protons spectrum (double) [MeV] - -

- EminP: min energy of trapped protons spectrum (double) [MeV] - -

- EmaxP: max energy of trapped protons spectrum (double) [MeV] - -

- NPTSP: number of spectrum points which divides proton spectra for integration. A value of 1001 is recommended (long integer). - -

- EminE: min energy of trapped electrons spectrum (double) [MeV] - -

- EmaxE: max energy of trapped electrons spectrum (double) [MeV] - -

- NPTSE: Number of spectrum points which divides electron spectra for integration. A value of 1001 is recommended (long integer). - -

- JSMAX: Number of points in falling spectrum of solar protons, max allowed=301 (long integer). - -

- JPMAX: Number of points in falling spectrum of trapped protons, max allowed=301 (long integer). - -

- JEMAX: Number of points in falling spectrum of trapped electrons, max allowed=301 (long integer). - -

- EUNIT: Conversion factor from /energy to /MeV; e.g. EUNIT = 1000 if flux is /keV (double). - -

- DURATN: Mission duration in multiples of unit time [s] (double). - -

- ESin: Energy array(301) of solar proton spectrum [MeV] (double). - -

- SFLUXin: Solar flare flux array(301) for solar protons [in /energy/cm2] (double). - -

- EPin: Energy array(301) of trapped proton spectrum [MeV] (double). - -

- PFLUXin: Incident omnidirectional flux array(301) for trapped protons [in /energy/cm2/s] (double). - -

- EEin: Energy array(301) of trapped electron spectrum [MeV] (double). - -

- EFLUXin: Incident omnidirectional flux array(301) for trapped electrons [in /energy/cm2/s] (double). - -

-

-

OUTPUTS: -

-

- SolDose: Dose profile array (71,3) for solar protons [rads] (double) -

    -
  1. Dose in semi-infinite aluminium medium
    2. -
  2. Dose at transmission surface of finite aluminium slab shields
    3. -
  3. 1/2 Dose at center of aluminium spheres
    4. -
-
-

-

- ProtDose: Dose profile array (71,3) for trapped protons [rads] (double) -

    -
  1. Dose in semi-infinite aluminium medium
    2. -
  2. Dose at transmission surface of finite aluminium slab shields
    3. -
  3. 1/2 Dose at center of aluminium spheres
    4. -
-
-

-

- ElecDose: Dose profile array (71,3) for trapped electrons [rads] (double) -

    -
  1. Dose in semi-infinite aluminium medium
    2. -
  2. Dose at transmission surface of finite aluminium slab shields
    3. -
  3. 1/2 Dose at center of aluminium spheres
    4. -
-
-

-

- BremDose: Dose profile array (71,3) for Bremsstrahlung [rads] (double) -

    -
  1. Dose in semi-infinite aluminium medium
    2. -
  2. Dose at transmission surface of finite aluminium slab shields
    3. -
  3. 1/2 Dose at center of aluminium spheres
    4. -
-
-

-

- TotDose: Total dose profile array (71,3) [rads] (double) -

    -
  1. Dose in semi-infinite aluminium medium
    2. -
  2. Dose at transmission surface of finite aluminium slab shields
    3. -
  3. 1/2 Dose at center of aluminium spheres
    4. -
-
-

-

-

-

CALLING SEQUENCE FROM MATLAB: -

-

- - [ProtDose,ElecDose,BremDose,SolDose,TotDose] = onera_desp_lib_shieldose2(ProtSpect,ElecSpect,SolSpect,Target,...) -  
-

-

CALLING SEQUENCE from IDL: -

-

- result = call_external(lib_name, 'shieldose2idl_', IDET,INUC,IMAX,IUNT,Zin,EMINS,EMAXS,EMINP,EMAXP,NPTSP,EMINE,EMAXE,NPTSE,JSMAX,JPMAX,JEMAX,EUNIT,DURATN,ESin,SFLUXin,EPin,PFLUXin,EEin,EFLUXin,SolDose,ProtDose,ElecDose,BremDose,TotDose,/f_value) -

-

CALLING SEQUENCE from FORTRAN: -

-

- CALL shieldose2(IDET,INUC,IMAX,IUNT,Zin,EMINS,EMAXS,EMINP,EMAXP,NPTSP,EMINE,EMAXE,NPTSE,JSMAX,JPMAX,JEMAX,EUNIT,DURATN,ESin,SFLUXin,EPin,PFLUXin,EEin,EFLUXin,SolDose,ProtDose,ElecDose,BremDose,TotDose)
-

-   - - - diff --git a/docs/frames/header.html b/docs/frames/header.html deleted file mode 100755 index bedc231c..00000000 --- a/docs/frames/header.html +++ /dev/null @@ -1,30 +0,0 @@ - - - - -IRBEM-LIB - - -
-         IRBEM library user's guide -          -
- - \ No newline at end of file diff --git a/docs/frames/how2build.html b/docs/frames/how2build.html deleted file mode 100755 index bf8d70ee..00000000 --- a/docs/frames/how2build.html +++ /dev/null @@ -1,134 +0,0 @@ - - - - - -

INTRODUCTION -

-
-

- !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! WARNING !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -

-    You must have a Fortran compiler in order to build the ONERA_DESP_LIB - distribution. -

- !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -

- Requests for assistance or documentation should be sent to: sebastien.bourdarie@onera.fr -

- If you get the distribution, please send to sebastien.bourdarie@onera.fr a message - so we can put you on our mailing list. That way you will be notified of new releases. -

- The use of the Makefile to build the library is highly recommended. Old scripts distributed - before are still provided but will not be maintained any more. The new Makefile allows - to build the library on various platforms, either 32 or 64 bits computers. It solves - the problems being encounter to built the library on new 64 bit linux box and run - it with IDL. -



-

-

INSTALLATION INSTRUCTIONS  -

-
-

- ONERA_DESP_LIB has a makefile setup to automatically build the library. The following - steps should be taken to build and install ONERA_DESP_LIB.

- - 1. Set your current directory (cd) to the top level ONERA_DESP_LIB - directory. -
-
- 2. Compile/link the distribution. First enter... -
-
- make all.help -
-
- For example, to build the distribution on a SunOS system using the gnu Fortran compiler - enter... -
-
- make OS=sunos ENV=gnu64 all -
-
- The `OS' and `ENV' variables are described in the `make all.help' part of this step. -
-
-
- 3. Install the libraries. First enter... -
-
- make install.help -
-
- To determine the required/optional `make' variables to be used. -
-
- Then enter... -
-
- make `make variables...' install -
-
- The appropriate files will be copied to the `matlab' and top level ONERA_DESP_LIB - directories (from the `source/...' directory). -
-
- For example, to install the distribution in `/usr/local/onera_desp_lib' enter... -
-
- make INSTALLDIR=/usr/local/onera_desp_lib install -
-
- The `INSTALLDIR' variable is described in the `make install.help' part of this step. -
-
-
- 4. Test that the distribution was built correctly. -
-
- First enter... -
-
- make test.help -
-
- To determine the required/optional `make' variables to be used. -
-
- Then enter... -
-
- make `make variables...' test -
-
- The name of each test executed and results will be displayed. -
-
-
- 5. Delete the libraries, object files, and executables in - the `source/...' directory by entering... -
-
- make clean -
- -

- - diff --git a/docs/frames/idl.html b/docs/frames/idl.html deleted file mode 100755 index c932b805..00000000 --- a/docs/frames/idl.html +++ /dev/null @@ -1,82 +0,0 @@ - - - - - -

INTRODUCTION -

-
-

- We provide a set of IDL wrappers - for the ONERA/DESP FORTRAN library through the use of a shared library file (.dll - on windows, .so on Unix). IDL access to any FORTRAN function with the use of the IDL - function CALL_EXTERNAL (see IDL manual for more details). -

-

-

-

-

-

INSTALLATION -

-

-

-

- The ONERA/DESP compile scripts will create - the shared library file for use with IDL (or Matlab) and is given a name "onera_desp_lib_OS.dll" - or "onera_desp_lib_OS.so" depending on the platform, where OS can be either sunos_sparc, - sunos_sparcV9, linux_x86, linux_x86_64, Win32_x86. The lib_name can be defined from - IDL by the following: -

-

- case !version.os of -
-    'linux':ext='so' -
-    'sunos':ext='so' -
-    'Win32':ext='dll' -
- endcase -
- lib_name=onera_desp_lib_+'_'+!version.os+'_'+!version.arch+'.'+ext -

-

- Thus, in order to access the library and - the wrappers, the user needs only to use the CALL_EXTERNAL function where "image" - (here refers as lib_name in the detailled function descriptions) provide the path+name - of the shared library file.  -
-   -

-

-

-

USE OF THE LIBRARY -

-

-

-

- When calling from IDL using call_external, - ALL input and output variables have to - be declared in the correct  type. Failure to do this will result in a very ungracefull - idl exit with no error messages or possibility of tracing! In general, integers need - to be declared as longs and floats as double.  -

- - diff --git a/docs/frames/introduction.html b/docs/frames/introduction.html deleted file mode 100755 index 7ae5df02..00000000 --- a/docs/frames/introduction.html +++ /dev/null @@ -1,148 +0,0 @@ - - - - - - -
- See source repository for version and release details -
- Authors and contributors
D. - Boscher, S. Bourdarie - ONERA-DESP, Toulouse France -
- T. Paul O'Brien, T. Guild - The Aerospace Corporation - USA -
and
- D. Heynderickx, S. Morley, A. Kellerman, C. Roth, H. Evans, A. Brunet, M. Shumko, C. Lemon, S. Claudepierre, T. Nilsson -
and the IRBEM contributor community - -
-
 
- For - any questions or to report bugs please visit the issue tracker at - the source repository on GitHub - -
- - -
-
-
-

- The International Radiation Belt Environment Modeling (IRBEM) library is freely distributed under the - umbrella of COSPAR's PRBEM (Panel on Radiation Belt Modeling.
- In 2003 ONERA-DESP (space environment department) decided to put together a set of source codes into a - library dedicated to radiation belt modeling. The toolkit was then called ONERA-DESP-LIB. Because the project has grown - with time, and because its development is now an international collaborative effort, it was decided in 2008, - after COSPAR 2008 Montreal assembly, to change the library name to IRBEM-LIB (which refers to COSPAR PRBEM panel) and to - distribute it under the COSPAR PRBEM umbrella (a neutral body). -

-

-
- The following document describes how to - use the IRBEM fortran library (formerly the ONERA-DESP library) to compute magnetic coordinates and drift shells - using various external magnetic field models.  Further routines are provided - for  various coordinate and time format transformations. -

-

- The library can be called from FORTRAN - or C code and from IDL or MATLAB code. For IDL and MATLAB wrappers are provided - in the distribution package.  -

-

- The package includes a Makefile - to built the library on various platform, install - it and test it (See section installation for more details).  -

-

- Two libraries are created, one for access - from IDL or MATLAB and one for access from fortran or some other language. -
-

-

-

-

- Notes: -
- -

-

- 1. The - bad value flag is set to  -1.d31 throughout. -
-
-

-

- Rule - of use: This library is free software: you can redistribute it and/or modify - it under the terms of the GNU Lesser General Public License as published by - the Free Software Foundation, either version 3 of the License, or - (at your option) any later version. - - This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public License - along with this library. If not, see http://www.gnu.org/licenses/.
- COSPAR does not warrant or assume any legal liability or responsibility for the accuracy, completeness, use, - or usefulness of any information, apparatus, product, or process disclosed in documents and software available - from the IRBEM library or developed as a result of the use of information or software made available from the library.
-
- To refer to this library in publications or reports, please provide the URL of the source repository (https://github.com/PRBEM/IRBEM) - and see the project README for additional, up-to-date citation details. - -

-

- Acknowledgments: - -

-
- - The authors wish to thank: -
    -
  • - K. Pfitzer, N. Tsyganenko, - I. Alexeev and their co-authors for providing us magnetic field model source codes - and for good discussions on how to use their models correctly. -
    • -
  • - R. Friedel (LANL), Y. Dotan and M. Redding (Aerospace corporation) for good discussions, advice and - bug reports which are always very helpfull when one attemps to develop such a tool. -
    • -
  • - D. Bilitza for his help regarding the use of IGRF magnetic field model and MSIS models. -
    • -
  • - D. Brautigam for providing - us CRRES models. -
    • -
  • - D. Vallado for providing free of use source code for orbit propagator (SGP4).
    -
    • -
-
-

-

-

- -

- - diff --git a/docs/frames/lgplv3-147x51.png b/docs/frames/lgplv3-147x51.png deleted file mode 100755 index b7dc74d3ebddd001d2cf1f5f5851bea99ab1715a..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 4224 zcmV-`5P$E9P)}rO==B=7hpi(rGH4vpN zU9>D=Enh&nso1`toM%?6mquQ;bu%?D<)x*hb$7!O+w$e*fXsNIKtaQ!Dage&K`sLE z>>uA5e$Q{t%>16;?>C3zOV8)^IW|09P6v{~18_k*NjaU`1!m>N_&R`HzK4O)eM>b2pm?? zVBZe-4`3MJ_4Ystuo2h<3b7T6#7Btj;DyMdV|h?ck6|7KvIE15>Md9$}0=9?hes6u~3FOTDQz<&difODSpEp7D zVih-1+WQD%fM42>Oe*vhqUKV}H9<7pI=_ha$+QIcIq(qB%pchw_z*A#IER|}-hvpu zJ6agaZpgzq0XQ4zNc!;+ah~4yv7~Jto=ASLZ{hy!;5p!5fc=1Lfp=TywgVdYt_h-6 zo=Xuf2HpU!cacoPfxWE#N74-y`U8=d*$$Qg$C@B|wZ-d~0C%X+Uj$JBA zFvl8$6A|nOx6%ZW9l-jS%Z*F01M5Yp(C-gS1NLyZ_B)w<+eyg2{7Jwm4t;*RpwG_C z@iHj z+u(~`=)!__-H4<@e=uSSOraL2v@yVC07`pP5gYY-qvM;?RIODDC|Na1FwR z3+!`^B-1g7HP+BPDS{opoJuUgtw zanPDN02fddBNh7RAYp=o9Pcs51kt>_ z6H0p>h;ctX>HiF)f-3a;A>oiRtj+BI zF&USWackiX;7s6t;2zw((JjEwXwKkY0*p67v?+Tckw`ZoL;^TH8P9Eb9d+a#1W=*> z0qSj{hplt_Ai>Ob(5eI}L)M5s2Db-WBz>MTLG%~v_z{$=7^shTk&LI=5WyzogZVY^ zpSTeT;5{@)q!qx}qJXi{@eZTovyl($bcA@fD(#(>*S?TU)W2Lq{mZZ7#kXpFm!T?q zX>^0*Wyq8E&8WKdh}!;N;4X?iwsz48j5a~EvQa~$8^|O+PRYHX%j^M zXYIGE;8leFR;ZbO2L(qZTipq6i}N-{m$LBV{60<1S!&MjNz(v4{hbTU1v>Ci}sy%anEQ zs$k{8NTr~SbAT>uzc5&-LVptO;fA3}Uk8?q(bfKXSHbal zE7k$$+ZB~b&T$-);C(L=8Gi*)e^G<}zJ!qf-n^4VWU?PzHonv@nKmM^7hq=wJ6nHK zgzQ+#(kK_v-pr6zqx1V09Dfi|orA1n*O?%?J=wknDe|uhPXeczAbLKjI~$Lv{qf|7 zH`Y)PxCBtzI~8#Vt~NUE7L$TvZ>}s@*)EwDnIQVBwSNq5lNHvQAo^3fld-%!Sh4AmHDTBD-%D zwd*FCROk<*KFe+gD-WXmucxY5(9zWFlQ@&0Of&wiVp%4TcNqEJW*&0MlwdA0V`Vk) zSrbItdO*E(B4saKxZAdun;`m4$@%Xg?|p39e7d{`Zok}go>ht}?4?%APRdkV)dA3U zqVr|>#R*8h?My3JIE`x6+i02_@3oW|{Yrb2km=&L8XeCsY6p$U^jOAiZZ}v7^_7*` z$qHpCvtg=E&1A{hOx`dz&7?yA2*iNZCWs!ePW9H@x~;%e6GT5QYM`|DNo0cNVjRL1 zc{Wo|+Dj`kQP&aFPgW?xcIqW0^emZLHNF83O+Jz=zKy82@23Y;=pRk{InGw_4Dg8t zMDmaVyp_PoM#l|j+SExV75eX_zL3kdmpYJ0u}gh$UAKr!53Q@XC+)1Z3jITPy{y&31w_X z?4(siZEa-LoNd&CC7F@{-ak4Hx;C)TKb#twT9qJK30XxkToD#!f|c27Qx^=!A`|dk zBtw5=rk%@-nW``s___(A7s?tb?Hz{1kp==M7#%<3dV?&PY;nHAb=pepk3bTlsL=lua2)UjyF4bTjVkl}s={)l9QVFP z4VCteM^u{u#v2_s3S!nFOD6lPUadlZBJJZd*7i44=x+oTm>}9*bU_}H*pUyMPkqiU zTi(&GU6++~u6T+XnMMIWNVfkO3DVw~X`eScq)Kc=CT3n$rqWU*HA=T2HqtnwMDp?MMJ}rU{}yH)^c3*AJP4cnRX`WP}=j6w963SBBSH%YAH>l zRWi+|e&*^B-0PIf@GHbEKLW{W7hydTOnW~PNZpKNz~4+5gV=9{tFf6N+Mq&z95O@q z%eblM^+>VZFMwZ|AZluH45hu@kXbG>kqM?J866i%&Zc0KsTnWmLL^s}dLvcTDSr{s z*+(Hd{5oVwn>?J46njla3f9`0PSjI44cL?X#Uyqjsk@r0LVp&r!tGeZ_Ueb&iklDv z{z)Xpw<0sE#~Dg{A3{FDqYxE)zR__N9=r5!j7gWqc@4MZ=z1h-y_}l8G6%^jZ$;*K zJ%mh=IR^1&_DKf+Z%DbxOzH!RYfTXCuR{O#$QOMrQd{)7WP1)$8+{Q%vdfTC-w&D~ zxvE0gPHQB6I1icwWBWz#GY zY4lCxnQQ>QW^{ae`Blv$4aPN-WnY-+=J5zIz6$&g;zeA5cvn{d0pe!gjI0cD0Ya>m zbYIPEZx#Bdn;<$KA;}j3K z3jO1$WtxW~b-`C5lHdd+_cJ~@KLM$MSxL>VnwIJF9^eNm^sfMZW`gM4B-nQ`B8kQz zlIj&idW=L!_dH^}9*9W4%aZMv5sCH)vh>W_WE>k16}yX&eZ;*QKQxSrsfysr`UjBZ-Z-H4!`RN%*j%*U59`8aV zlZTM$xa7KYRsJ=IRI18VPq9lEl~>x^TWRn6$Z95M06zpq^fZy6CYhQcQx~FtQ#_Ge zpJxB3BDz^25@{$hPyQQ-s<{x6DmJb})aA8^)JbzgS0lvR9my>nh^W!jFdvE(ZcRiC z@lON8lj+^xLWnpX_zGfl9)Ng#UDVP%CnA#ZproHOn|Ky3m_ql3$tp*(Ccrf0+3$te zh%=kXt+hP{L>xZ1t8Ul;hMrk(yr=qg#bgsixAa8EN_&SOAMj*^L=OO$7#;6&54S&W zu3%+Pz3|>%5dQ`h`mdQFnp;I@N_z^i6{jPTw*zr9W*Z&nE{n4(@Ma^^TNV9*yH)7V zHbFF_l@5{#kYfyz>xXA?3in4}Ed+$TY zGY;{R2O^UN79hE_+l-ET`@bOUghCd(?CEldKFAcKvoU4_qIP#69@m4&RIL<)5vg+s zwJL-)NQ`J6aG%j}PcI4G68ipm;Vwp!sXvZdXyr)iZMro`obDNfY`+C!qvJRIi~4`R W2lptfSHg4v0000. -% --> - - - - -

INTRODUCTION -

-

-

-

- We provide a set of Matlab wrappers for - the IRBEM FORTRAN library through the use of a shared library file (.dll on windows, - .so on Unix). Matlab refers to this type of interface as a "mex file". In addition - to the shared library file, Matlab requires a C-style header file that includes the - C-style calling syntax for each FORTRAN function. This .h file is provided with the - IRBEM Matlab library. For historical reasons, the Matlab routines and files are prefixed - with "onera_desp_lib" rather than "irbem". -

-

-

-

-

-

INSTALLATION -

-

-

-

- Easy way for 32-bit windows users: - - -

  • Manually create your top-level folder "irbem" -
  • Download the matlab folder tarball, - and untar/unzip its contents into a folder called "irbem\matlab" -
  • Download the data folder tarball, - and untar/unzip its contents into a folder called "irbem\data" -
  • Open Matlab -
  • Under the File menu, click "Set Path" -
  • Add "irbem\matlab" to your Matlab path -
  • Add "irbem\data" to your Matlab path -
  • Click "Save" to save your new Matlab path for future sessions -
  • Download the 32-bit - windows DLL and save it as "irbem\matlab\onera_desp_lib.dll" - - -

    - -

    - Sort of easy way for 64-bit windows users: -

      -
    • Do all the steps above, except download the 64-bit - windows DLL and save it as "irbem\matlab\onera_desp_lib.dll" -
    • Then you have to install the latest free Microsoft Visual Studio, including its "redistributables" (these are DLLs needed by the IRBEM library and Matlab requires this compiler to acceass any DLL) -
    • Then you have to add the following DLLs to the matlab folder where onera_desp_lib.dll resides. (We're working on a version of the DLL that does not have these dependencies): -
        -
      • (Except where noted, these are part of cygwin64, but can sometimes be found on-line without installing it) -
      • libgcc_s_seh-1.dll -
      • libgfortran-3.dll -
      • libquadmath-0.dll -
      • (These one may not be needed anymore, or only need for extras) -
      • libgsl-0.dll -
      • libgcc_s_sjlj-1.dll -
      • libgslcblas-0.dll -
      • IEShims.dll (usually found in the internet explorer folder, e.g., c:\program files\internet explorer. Copy it) -
      -
    -

    - -

    - Hard way for everyone else: - The IRBEM make file (call make help from irbem/trunk) will create - the shared library file for use with IDL or Matlab. A copy of the shared library is - created in the "matlab" subdirectory, and is given a name "onera_desp_lib.dll" or - "onera_desp_lib.so" depending on the platform. Thus, in order to access the library - and the wrappers, the user needs only add the "matlab" subdirectory (e.g. "c:\irbem\matlab") - to the Matlab path. In order for the library to easily locate the data files that - it needs, it is also advisable to add the "data" subdirectory to the Matlab path. - Matlab provides a GUI interface to add folders to the search path from "Set Path" - entry on the "File" menu. It is also possible to add these two folders to the path - using the Matlab "addpath" command; however, this command does not make the change - to the path permanent, so that "addpath" will have to be issued once in each new Matlab - session. The "savepath" function can make the path change permanent, as can the GUI - path manager interface. Thus, one could use the following commands, if the IRBEM library - is located in "c:\irbem": -
    -
    - addpath c:\irbem\matlab c:\irbem\data -
    - savepath     -

    -

    - -
    -       -

    -

    -

    -

    USE OF THE MATLAB LIBRARY -

    -

    -

    -

    - The Matlab wrappers are built to provide - Matlab-like function calls into the library. These wrappers handle loading the library - into Matlab's function space, formatting inputs and outputs for proper calls to the - library, and providing "vectorized" functionality wherever reasonable. Each wrapper - function will determine whether the FORTRAN library has been loaded, and, if not, - attempt to load it from the default location (anywhere in the Matlab path). -
    -
    - Each .m file provided includes a robust set of helps obtainable via help <funtion_name> - in the usual Matlab way. This help call will provide details of how to call the function. -
    -
    - Although the FORTRAN library often limits the size of arrays, the Matlab wrappers - typically handle arbitrarily large array inputs by splicing together multiple calls - to the library. Also, in many cases, when a set of arrays is expected as input, the - Matlab wrappers will accept scalars for some, which will be repeated (via Matlab's - repmat function) to be the same size as the other array arguments. -
    -
    - In many cases, the library requires integer inputs that represent different options, - e.g., kext=5 for the Olson-Pfitzer Quiet external field model. In most cases, the - Matlab wrapper supports string (keyword) inputs in place of the integer values. This - keyword approach is implemented for kext, options, sysaxes, and whichm, among others. -
    -
    - Whenever date/time arguments are required by the FORTRAN library, the Matlab library - expects Matlab Date Numbers (construct argument "matlabd" with Matlab's datenum function). -
    -
    - The FORTRAN library function fly_in_afrl_crres requires a set of text files. If the - path to these files is not specified, the wrapper will attempt to guess it by locating - one of these, 'crrespro_quiet.txt' in the Matlab search path. -
    -
    - When available from MATLAB a calling sequence is provided for each function (see detailled - description of each functions). -
    -

    -

    -

    -

    HELPER FUNCTIONS -

    -

    - Helper functions that support the wrappers: -
    - The following function creates the proper maginputs array for use with the field models. -
    - maginputs = onera_desp_lib_maginputs(Kp,Dst,Nsw,Vsw,Psw,ByGSM,BzGSM,G1,G2,G3,W1,W2,W3,W4,W5,W6,AL); -
    -
    - The following funnction will load the shared library file from the non-default location. -
    - onera_desp_lib_load(libfile,headerfile); -
    -
    - The following functions are used by the library to convert the Matlab wrapper inputs - into the inputs needed by the FORTRAN library. These include "as appropriate" the - look-up tables that convert keyword inputs into the integer constants used by the - FORTAN library. -
    - kext = onera_desp_lib_kext(kext); -
    - options = onera_desp_lib_options(inoptions); -
    - sysaxes = onera_desp_lib_sysaxes(sysaxes) ; -
    - [iyear,idoy,UT] = onera_desp_lib_matlabd2yds(matlabd); -
    -     -

    - - diff --git a/docs/frames/opened.gif b/docs/frames/opened.gif deleted file mode 100755 index 1b328f45494b58cb2275c41ca687779f61992781..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 826 zcmZ?wbhEHbWM^P!_|CvEXAZ;vQ7{?;BQ*pRf3h$#FfcOcFaQB4PdIRhGca?=SO_#Y WHnIuJshpUw(20RXk&B0e!5RQSGz63Y diff --git a/docs/frames/python.html b/docs/frames/python.html deleted file mode 100644 index 3949d605..00000000 --- a/docs/frames/python.html +++ /dev/null @@ -1,72 +0,0 @@ - - - - - -

    INTRODUCTION -

    -

    - We provide a set of Python wrappers for - the IRBEM Fortran library through the use of a shared library file (.so on Unix). - The wrapper is found in python/IRBEM.py. Python interfaces with the compiled shared - library file with ctypes. -

    -

    INSTALLATION -

    -

    - - -

  • Compile the Fortran source as instructed by the README.install file. - This will create the shared object file, "onera_desp_lib_linux....so" in the - source firectory.
    • -
  • Change directory into the python folder and add the Python wrapper paths - with "sudo python3 setup.py install"
    • -
  • Check that the installation worked by running the provided test scripts - (...tests_and_visualizations.py).
    • -
  • If the wrapper crashes with the error "Either none or multiple .so files - found in the sources folder!", check that the shared object exists in the - source folder.
    • -     - - -

    - -

    HOW TO USE -

    -

    -

    -

    - - The Python wrapper IRBEM.py currently consists of two classes that load the shared object file. - This class interface is used to avoid redudant user input formatting code. IRBEM.py currently - contains wrappers for the magnetic field library via the "MagFields" class and coordinate - transformation library via the "Coords" class. The two classes contain methods which interface - with the various IRBEM functions e.g. make_lstar. The output from each IRBEM wrapped function - can be accesed with the usual return statement and "**FUNCTION_NAME**_output" class attributes. -
    -
    - Current wrapped magnetic field functions are make_lstar, drift_shell, find_mirror_point, - find_foot_point, trace_field_line, and find_magequator. For more documentation, call help(FUNCTION_NAME). -
    -
    - Example code can be found in the ...test_and_visualizations.py files. -

    - - diff --git a/docs/index.html b/docs/index.html deleted file mode 100755 index 18767ca5..00000000 --- a/docs/index.html +++ /dev/null @@ -1,32 +0,0 @@ - - - - - IRBEM library user's guide - - - - - - - - - - diff --git a/docs/source/_ext/routine.py b/docs/source/_ext/routine.py new file mode 100644 index 00000000..d7aec306 --- /dev/null +++ b/docs/source/_ext/routine.py @@ -0,0 +1,156 @@ +from collections import defaultdict + +from docutils.parsers.rst import directives + +from sphinx import addnodes +from sphinx.application import Sphinx +from sphinx.directives import ObjectDescription +from sphinx.domains import Domain, Index +from sphinx.roles import XRefRole +from sphinx.util.nodes import make_refnode +from docutils import nodes +from sphinx.util.docfields import TypedField, GroupedField + +class CallSeqField(GroupedField): + def __init__(self): + super().__init__('callseq', ('callseq',), 'Calling sequence') + + def make_entry(self, field_arg, content): + call = content[0].astext() + literal = nodes.literal_block(call, call) + literal['language'] = field_arg + container_node = nodes.container('', literal_block=True, + classes=['callseq-block-wrapper']) + container_node += nodes.caption(field_arg, 'From '+field_arg) + container_node += literal + return field_arg, container_node + + def make_field(self, types, domain, items, env, inliner, location): + fieldname = nodes.field_name('', self.label) + listnode = nodes.container(classes=['callseq-field']) + for fieldarg, content in items: + listnode += content + fieldbody = nodes.field_body('', listnode) + return nodes.field('', fieldname, fieldbody, ) + +class RoutineDirective(ObjectDescription): + """A custom directive that describes a subroutine.""" + + has_content = True + required_arguments = 1 + option_spec = { + 'contains': directives.unchanged_required, + } + doc_field_types = [ + CallSeqField(), + TypedField('parameters', label='Inputs', + names=('param','input'), typenames=('type',),), + TypedField('outputs', label='Outputs', + names=('out','output'), typenames=('type',),), + + ] + + def handle_signature(self, sig, signode): + signode['name'] = sig + signode += addnodes.desc_name(text=sig) + return sig + + + def add_target_and_index(self, name_cls, sig, signode): + node_id = 'routine-'+sig + signode['ids'].append(node_id) + irbem = self.env.get_domain('irbem') + irbem.add_routine(sig) + self.indexnode['entries'].append(('single', sig, node_id, '', + sig[0].upper())) + + def _toc_entry_name(self, signode): + return signode['name'] + + def _object_hierarchy_parts(self, signode): + return (self._toc_entry_name(signode),) + +class RoutineIndex(Index): + """A custom index that creates an routine matrix.""" + + name = 'routines' + localname = 'Routines Index' + shortname = 'Routine' + + def generate(self, docnames=None): + content = defaultdict(list) + # sort the list of recipes in alphabetical order + routines = self.domain.get_objects() + routines = sorted(set(routines), key=lambda routine: routine[0]) + + # generate the expected output, shown below, from the above using the + # first letter of the recipe as a key to group thing + # + # name, subtype, docname, anchor, extra, qualifier, description + for _name, dispname, typ, docname, anchor, _priority in routines: + content[dispname[0].upper()].append(( + dispname, + 0, + docname, + anchor, + docname, + '', + typ, + )) + # convert the dict to the sorted list of tuples expected + content = sorted(content.items()) + return content, True + +class IRBEMDomain(Domain): + name = 'irbem' + label = 'IrbemLabel' + roles = { + 'ref': XRefRole(), + } + directives = { + 'routine': RoutineDirective, + } + indices = { + RoutineIndex, + } + initial_data = { + 'routines': [], # object list + } + + def get_full_qualified_name(self, node): + return f'routine.{node.arguments[0]}' + + def get_objects(self): + yield from self.data['routines'] + + def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode): + match = [ + (docname, anchor) + for name, sig, typ, docname, anchor, prio in self.get_objects() + if sig.upper() == target.upper() + ] + + if len(match) > 0: + todocname = match[0][0] + targ = match[0][1] + + return make_refnode(builder, fromdocname, todocname, targ, contnode, targ) + else: + print('Awww, found nothing') + return None + + def add_routine(self, signature): + """Add a new routine to the domain.""" + name = f'routine.{signature}' + anchor = f'routine-{signature}' + + # name, dispname, type, docname, anchor, priority + self.data['routines'].append((name, signature, 'Routine', self.env.docname, anchor, 0)) + +def setup(app: Sphinx): + app.add_domain(IRBEMDomain) + return { + 'version': '0.1', + 'parallel_read_safe': True, + 'parallel_write_safe': True, + } diff --git a/docs/source/_static/css/irbem.css b/docs/source/_static/css/irbem.css new file mode 100644 index 00000000..4e9f1536 --- /dev/null +++ b/docs/source/_static/css/irbem.css @@ -0,0 +1,46 @@ +dl.field-list > dt { + min-width : 10em; +} + +dl.irbem dl.field-list { + grid-template-columns: 10em auto !important; + display: block !important; +} + +dl.field-list > dd:has(> div.callseq-field) { + grid-column: 1/3; +} + +dl.field-list > dd > ul > li { + padding-left: 1.25rem; +} + +dl.field-list > dd > ul > li > p:first-child { + margin-left: -1.25rem; +} + +p { + font-size: 0.9em; +} + +p:has(+ ul) { + margin-bottom: 0.15rem; +} + +table.table ul.simple { + padding-left: 0; +} + +table.table ul.simple li::marker { + content: ''; +} + +dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dd { + margin-left: 1rem; +} + +dl.field-list dd ul li p em { + font-family: monospace; + font-style: normal; + color: var(--pst-color-muted); +} diff --git a/docs/frames/Lstar.jpg b/docs/source/api/Lstar.jpg similarity index 100% rename from docs/frames/Lstar.jpg rename to docs/source/api/Lstar.jpg diff --git a/docs/source/api/api.rst b/docs/source/api/api.rst new file mode 100644 index 00000000..258e95f1 --- /dev/null +++ b/docs/source/api/api.rst @@ -0,0 +1,15 @@ +API Reference +============= + +.. toctree:: + :maxdepth: 1 + + general_information + magnetic_coordinates + coordinates_transformations + radiation_models + atmospheric_models + orbit_propagation + date_and_time + library_infos + diff --git a/docs/source/api/atmospheric_models.rst b/docs/source/api/atmospheric_models.rst new file mode 100644 index 00000000..15be4a54 --- /dev/null +++ b/docs/source/api/atmospheric_models.rst @@ -0,0 +1,198 @@ +Atmospheric models +================== + +.. irbem:routine:: MSIS86 + + The Mass-Spectrometer-Incoherent-Scatter-1986 (MSIS-86) neutral atmosphere + model describes the neutral temperature and the densities of He, O, N2, O2, + Ar, H, and N. The MSIS model is based on the extensive data compilation and + analysis work of A. E. Hedin and his collaborators [A. E. Hedin et al., J. + Geophys. Res. 82, 2139-2156, 1977; A. E. Hedin, J. Geophys. Res. 88, 10170- + 10188, 1983; A. E. Hedin, J. Geophys. Res. 92, 4649, 1987]. MSIS-86 + constitutes the upper part of the COSPAR International Reference Atmosphere + (CIRA-86). + + Data sources for the present model include temperature and density + measurements from several rockets, satellites (OGO-6, San Marco 3, Aeros-A, + AE-C, AE-D, AE-E, ESRO 4 and DE-2) and incoherent scatter radars (Millstone + Hill, St. Santin, Arecibo, Jicamarca, and Malvern). Since the MSIS-83 model, + terms were added or changed to better represent seasonal variations in the + polar regions under both quiet and magnetically disturbed conditions and + local time variations in the magnetic activity effect. In addition a new + species, atomic nitrogen, was added to the list of species covered by the + model. + + :param integer ntime: number of time points + :param integer whichAp: key for the kind of Ap input: + + * 1 - only daily Ap magnetic index is provided in the `Ap` parameter + * 2 - all fields are provided in the `Ap` parameter + + :param array of `ntime` integer idoy: the day of year (January 1st is `idoy=1`) + :param array of `ntime` double UT: the time in seconds + :param array of `ntime` double alt: altitude (km, greater than 85km) + :param array of `ntime` double lat: geodetic latitude (deg) + :param array of `ntime` double long: geodetic longitude (deg) + :param array of `ntime` double F107A: 3 month average of F10.7 flux + :param array of `ntime` double F107: daily F10.7 flux for previous day + :param array of [7, `ntime`] double Ap: averaged Ap index + + * 1 - Daily Ap + * 2 - 3 hours Ap index for current time + * 3 - 3 hours Ap index for 3 hours before current time + * 4 - 3 hours Ap index for 6 hours before current time + * 5 - 3 hours Ap index for 9 hours before current time + * 6 - Average of eight 3 hours Ap indices from 12 to 33 hours before current time + * 7 - Average of eight 3 hours Ap indices from 36 to 59 hours before current time + + :output array of [8, `ntime`] double dens: density: + + * 1 - He number density (cm\ :sup:`-3`) + * 2 - O number density (cm\ :sup:`-3`) + * 3 - N\ :sub:`2` number density (cm\ :sup:`-3`) + * 4 - O\ :sub:`2` number density (cm\ :sup:`-3`) + * 5 - Ar number density (cm\ :sup:`-3`) + * 6 - Total mass density (g.cm\ :sup:`-3`) + * 7 - H number density (cm\ :sup:`-3`) + * 8 - N number density (cm\ :sup:`-3`) + + :output array of [2, `ntime`] double temp: temperature: + + * 1 - Exospheric temperature (K) + * 2 - Temperature at altitude (K) + + :callseq MATLAB: out = onera_desp_lib_msis('msis86',date,X,sysaxes,F107A,F107,Ap) + :callseq IDL: result = call_external(lib_name, 'msis86_idl_', ntime,whichAp,DOY,UT,Alt,Lat,Lon,F107A,F107,Ap,Dens,Temp, /f_value) + :callseq FORTRAN: CALL msis86(ntime,whichAp,DOY,UT,Alt,Lat,Lon,F107A,F107,Ap,Dens,Temp) + + +.. irbem:routine:: MSISE90 + + The MSISE model describes the neutral temperature and densities in Earth's + atmosphere from ground to thermospheric heights. Below 72.5 km the model is + primarily based on the MAP Handbook (Labitzke et al., 1985) tabulation of + zonal average temperature and pressure by Barnett and Corney, which was also + used for the CIRA-86. Below 20 km these data were supplemented with averages + from the National Meteorological Center (NMC). In addition, pitot tube, + falling sphere, and grenade sounder rocket measurements from 1947 to 1972 + were taken into consideration. Above 72.5 km MSISE-90 is essentially a + revised MSIS-86 model taking into account data derived from space shuttle + flights and newer incoherent scatter results. For someone interested only in + the thermosphere (above 120 km), the author recommends the MSIS-86 model. + MSISE is also not the model of preference for specialized tropospheric work. + It is rather for studies that reach across several atmospheric boundaries. + + :param integer ntime: number of time points + :param integer whichAp: key for the kind of Ap input: + + * 1 - only daily Ap magnetic index is provided in the `Ap` parameter + * 2 - all fields are provided in the `Ap` parameter + + :param array of `ntime` integer idoy: the day of year (January 1st is `idoy=1`) + :param array of `ntime` double UT: the time in seconds + :param array of `ntime` double alt: altitude (km, greater than 85km) + :param array of `ntime` double lat: geodetic latitude (deg) + :param array of `ntime` double long: geodetic longitude (deg) + :param array of `ntime` double F107A: 3 month average of F10.7 flux + :param array of `ntime` double F107: daily F10.7 flux for previous day + :param array of [7, `ntime`] double Ap: averaged Ap index + + * 1 - Daily Ap + * 2 - 3 hours Ap index for current time + * 3 - 3 hours Ap index for 3 hours before current time + * 4 - 3 hours Ap index for 6 hours before current time + * 5 - 3 hours Ap index for 9 hours before current time + * 6 - Average of eight 3 hours Ap indices from 12 to 33 hours before current time + * 7 - Average of eight 3 hours Ap indices from 36 to 59 hours before current time + + :output array of [8, `ntime`] double dens: density: + + * 1 - He number density (cm\ :sup:`-3`) + * 2 - O number density (cm\ :sup:`-3`) + * 3 - N\ :sub:`2` number density (cm\ :sup:`-3`) + * 4 - O\ :sub:`2` number density (cm\ :sup:`-3`) + * 5 - Ar number density (cm\ :sup:`-3`) + * 6 - Total mass density (g.cm\ :sup:`-3`) + * 7 - H number density (cm\ :sup:`-3`) + * 8 - N number density (cm\ :sup:`-3`) + + :output array of [2, `ntime`] double temp: temperature: + + * 1 - Exospheric temperature (K) + * 2 - Temperature at altitude (K) + + :callseq MATLAB: out = onera_desp_lib_msis('msise90',date,X,sysaxes,F107A,F107,Ap) + :callseq IDL: result = call_external(lib_name, 'msise90_idl_', ntime,whichAp,DOY,UT,Alt,Lat,Lon,F107A,F107,Ap,Dens,Temp, /f_value) + :callseq FORTRAN: CALL msise90(ntime,whichAp,DOY,UT,Alt,Lat,Lon,F107A,F107,Ap,Dens,Temp) + + +.. irbem:routine:: NRLMSISE00 + + The NRLMSIS-00 empirical atmosphere model was developed by Mike Picone, Alan + Hedin, and Doug Drob based on the MSISE90 model. The main differences to + MSISE90 are noted in the comments at the top of the computer code. They + involve: + + #. the extensive use of drag and accelerometer data on total mass density, + #. the addition of a component to the total mass density that accounts for + possibly significant contributions of O+ and hot oxygen at altitudes + above 500 km, and + #. the inclusion of the SMM UV occultation data on [O2]. + + The MSISE90 model describes the neutral temperature and densities in Earth's + atmosphere from ground to thermospheric heights. Below 72.5 km the model is + primarily based on the MAP Handbook (Labitzke et al., 1985) tabulation of + zonal average temperature and pressure by Barnett and Corney, which was also + used for the CIRA-86. Below 20 km these data were supplemented with averages + from the National Meteorological Center (NMC). In addition, pitot tube, + falling sphere, and grenade sounder rocket measurements from 1947 to 1972 + were taken into consideration. Above 72.5 km MSISE-90 is essentially a + revised MSIS-86 model taking into account data derived from space shuttle + flights and newer incoherent scatter results. For someone interested only in + the thermosphere (above 120 km), the author recommends the MSIS-86 model. + MSISE is also not the model of preference for specialized tropospheric work. + It is rather for studies that reach across several atmospheric boundaries. + + :param integer ntime: number of time points + :param integer whichAp: key for the kind of Ap input: + + * 1 - only daily Ap magnetic index is provided in the `Ap` parameter + * 2 - all fields are provided in the `Ap` parameter + + :param array of `ntime` integer idoy: the day of year (January 1st is `idoy=1`) + :param array of `ntime` double UT: the time in seconds + :param array of `ntime` double alt: altitude (km, greater than 85km) + :param array of `ntime` double lat: geodetic latitude (deg) + :param array of `ntime` double long: geodetic longitude (deg) + :param array of `ntime` double F107A: 3 month average of F10.7 flux + :param array of `ntime` double F107: daily F10.7 flux for previous day + :param array of [7, `ntime`] double Ap: averaged Ap index + + * 1 - Daily Ap + * 2 - 3 hours Ap index for current time + * 3 - 3 hours Ap index for 3 hours before current time + * 4 - 3 hours Ap index for 6 hours before current time + * 5 - 3 hours Ap index for 9 hours before current time + * 6 - Average of eight 3 hours Ap indices from 12 to 33 hours before current time + * 7 - Average of eight 3 hours Ap indices from 36 to 59 hours before current time + + :output array of [9, `ntime`] double dens: density: + + * 1 - He number density (cm\ :sup:`-3`) + * 2 - O number density (cm\ :sup:`-3`) + * 3 - N\ :sub:`2` number density (cm\ :sup:`-3`) + * 4 - O\ :sub:`2` number density (cm\ :sup:`-3`) + * 5 - Ar number density (cm\ :sup:`-3`) + * 6 - Total mass density (g.cm\ :sup:`-3`) + * 7 - H number density (cm\ :sup:`-3`) + * 8 - N number density (cm\ :sup:`-3`) + * 9 - Anomalous oxygen number density (cm\ :sup:`-3`) + + :output array of [2, `ntime`] double temp: temperature: + + * 1 - Exospheric temperature (K) + * 2 - Temperature at altitude (K) + + :callseq MATLAB: out = onera_desp_lib_msis('nrlmsise00',date,X,sysaxes,F107A,F107,Ap) + :callseq IDL: result = call_external(lib_name, 'nrlmsise00_idl_', ntime,whichAp,DOY,UT,Alt,Lat,Lon,F107A,F107,Ap,Dens,Temp, /f_value) + :callseq FORTRAN: CALL nrlmsise00(ntime,whichAp,DOY,UT,Alt,Lat,Lon,F107A,F107,Ap,Dens,Temp) diff --git a/docs/source/api/coordinates_transformations.rst b/docs/source/api/coordinates_transformations.rst new file mode 100644 index 00000000..96f27bfe --- /dev/null +++ b/docs/source/api/coordinates_transformations.rst @@ -0,0 +1,351 @@ +Coordinates transformations +=========================== + +.. irbem:routine:: COORD_TRANS_VEC + + Generic coordinates transformation from one geophysical or heliospheric + coordinate system to another. + + :param integer ntime: number of time points + :param integer sysaxesIN: key for the input coordinate system (see :ref:`sysaxes`) + :param integer sysaxesOUT: key for the output coordinate system (see :ref:`sysaxes`) + :param array of `ntime` integer iyear: the year + :param array of `ntime` integer idoy: the day of year (January 1st is `idoy=1`) + :param array of `ntime` double UT: the time in seconds + :param array of [3, `ntime`] double xIN: position in input coordinates system + :output array of [3, `ntime`] double xOUT: position in output coordinates system + :callseq MATLAB: Y=onera_desp_lib_coord_trans(X,rotation,matlabd) + :callseq IDL: result = call_external(lib_name, 'coord_trans_vec_', ntime,sysaxesIN,sysaxesOUT,iyr,idoy,secs,xIN,xOUT, /f_value) + :callseq FORTRAN: call coord_trans_vec1(ntime,sysaxesIN,sysaxesOUT,iyr,idoy,secs,xIN,xOUT) + +Geographic coordinates transformations +-------------------------------------- + +.. irbem:routine:: GEO2GSM + + Transforms :ref:`GEO ` to :ref:`GSM ` coordinates. + + :param integer iyr: the year + :param integer idoy: the day of year (January 1st is `idoy=1`) + :param double UT: the time in seconds + :param array of 3 double xGEO: cartesian position in GEO (Re) + :output double psi: angle for GSM coordinate + :output array of 3 double xGSM: cartesian position in GSM (Re) + :callseq MATLAB: xGSM = onera_desp_lib_rotate(xGEO,'geo2gsm',matlabd); + [xGSM,psi] = onera_desp_lib_rotate(xGEO,'geo2gsm',matlabd); + :callseq IDL: result = call_external(lib_name, 'geo2gsm_', iyr,idoy,secs,psi,xGEO,xGSM, /f_value) + :callseq FORTRAN: call geo2gsm1(iyr,idoy,secs,psi,xGEO,xGSM) + +.. irbem:routine:: GSM2GEO + + Transforms :ref:`GSM ` to :ref:`GEO ` coordinates. + + :param integer iyr: the year + :param integer idoy: the day of year (January 1st is `idoy=1`) + :param double UT: the time in seconds + :param array of 3 double xGSM: cartesian position in GSM (Re) + :output double psi: angle for GSM coordinate + :output array of 3 double xGEO: cartesian position in GEO (Re) + :callseq MATLAB: xGEO = onera_desp_lib_rotate(xGSM,'gsm2geo',matlabd); + [xGEO,psi] = onera_desp_lib_rotate(xGSM,'gsm2geo',matlabd); + :callseq IDL: result = call_external(lib_name, 'gsm2geo_', iyr,idoy,secs,psi,xGSM,xGEO, /f_value) + :callseq FORTRAN: call gsm2geo1(iyr,idoy,secs,psi,xGSM,xGEO) + +.. irbem:routine:: GEO2GSE + + Transforms :ref:`GEO ` to :ref:`GSE ` coordinates. + + :param integer iyr: the year + :param integer idoy: the day of year (January 1st is `idoy=1`) + :param double UT: the time in seconds + :param array of 3 double xGEO: cartesian position in GEO (Re) + :output array of 3 double xGSE: cartesian position in GSE (Re) + :callseq MATLAB: xGSE = onera_desp_lib_rotate(xGEO,'geo2gse',matlabd); + :callseq IDL: result = call_external(lib_name, 'geo2gse_', iyr,idoy,secs,xGEO,xGSE, /f_value) + :callseq FORTRAN: call geo2gse1(iyr,idoy,secs,xGEO,xGSE) + +.. irbem:routine:: GSE2GEO + + Transforms :ref:`GSE ` to :ref:`GEO ` coordinates. + + :param integer iyr: the year + :param integer idoy: the day of year (January 1st is `idoy=1`) + :param double UT: the time in seconds + :param array of 3 double xGSE: cartesian position in GSE (Re) + :output array of 3 double xGEO: cartesian position in GEO (Re) + :callseq MATLAB: xGEO = onera_desp_lib_rotate(xGSE,'gse2geo',matlabd); + :callseq IDL: result = call_external(lib_name, 'gse2geo_', iyr,idoy,secs,xGSE,xGEO, /f_value) + :callseq FORTRAN: call gse2geo1(iyr,idoy,secs,xGSE,xGEO) + +.. irbem:routine:: GEO2GDZ + Transforms :ref:`GEO ` to :ref:`GDZ ` coordinates. + + :param double xx: xGEO (Re) + :param double yy: yGEO (Re) + :param double zz: zGEO (Re) + :output double lati: latitude (deg) + :output double longi: East longitude (deg) + :output double alti: altitude (km) + :callseq MATLAB: xGDZ = onera_desp_lib_rotate([xx(:) yy(:) zz(:)],'geo2gdz'); + alti = xGDZ(:,1); lati = xGDZ(:,2); longi = xGDZ(:,3); + :callseq IDL: result = call_external(lib_name, 'geo2gdz_', xx,yy,zz,lati,longi,alti, /f_value) + :callseq FORTRAN: call geo_gdz(xx,yy,zz,lati,longi,alti) + +.. irbem:routine:: GDZ2GEO + Transforms :ref:`GDZ ` to :ref:`GEO ` coordinates. + + :param double lati: latitude (deg) + :param double longi: East longitude (deg) + :param double alti: altitude (km) + :output double xx: xGEO (Re) + :output double yy: yGEO (Re) + :output double zz: zGEO (Re) + :callseq MATLAB: xGEO = onera_desp_lib_rotate([alti(:), lati(:), longi(:)],'gdz2geo'); + xx = xGEO(:,1); yy = xGEO(:,2); zz = xGEO(:,3); + :callseq IDL: result = call_external(lib_name, 'gdz2geo_', lati,longi,alti,xx,yy,zz, /f_value) + :callseq FORTRAN: call gdz_geo(lati,longi,alti,xx,yy,zz) + +.. irbem:routine:: GEO2GEI + + Transforms :ref:`GEO ` to :ref:`GEI ` coordinates. + + :param integer iyr: the year + :param integer idoy: the day of year (January 1st is `idoy=1`) + :param double UT: the time in seconds + :param array of 3 double xGEO: cartesian position in GEO (Re) + :output array of 3 double xGEI: cartesian position in GEI (Re) + :callseq MATLAB: xGEI = onera_desp_lib_rotate(xGEO,'geo2gei',matlabd); + :callseq IDL: result = call_external(lib_name, 'geo2gei_', iyr,idoy,secs,xGEO,xGEI, /f_value) + :callseq FORTRAN: call geo2gei1(iyr,idoy,secs,xGEO,xGEI) + +.. irbem:routine:: GEI2GEO + + Transforms :ref:`GEI ` to :ref:`GEO ` coordinates. + + :param integer iyr: the year + :param integer idoy: the day of year (January 1st is `idoy=1`) + :param double UT: the time in seconds + :param array of 3 double xGEI: cartesian position in GEI (Re) + :output array of 3 double xGEO: cartesian position in GEO (Re) + :callseq MATLAB: xGEO = onera_desp_lib_rotate(xGEI,'gei2geo',matlabd); + :callseq IDL: result = call_external(lib_name, 'gei2geo_', iyr,idoy,secs,xGEI,xGEO, /f_value) + :callseq FORTRAN: call gei2geo1(iyr,idoy,secs,xGEI,xGEO) + +.. irbem:routine:: GEO2SM + + Transforms :ref:`GEO ` to :ref:`SM ` coordinates. + + :param integer iyr: the year + :param integer idoy: the day of year (January 1st is `idoy=1`) + :param double UT: the time in seconds + :param array of 3 double xGEO: cartesian position in GEO (Re) + :output array of 3 double xSM: cartesian position in SM (Re) + :callseq MATLAB: xSM = onera_desp_lib_rotate(xGEO,'geo2sm',matlabd); + :callseq IDL: result = call_external(lib_name, 'geo2sm_', iyr,idoy,secs,xGEO,xSM, /f_value) + :callseq FORTRAN: call geo2sm1(iyr,idoy,secs,xGEO,xSM) + +.. irbem:routine:: SM2GEO + + Transforms :ref:`SM ` to :ref:`GEO ` coordinates. + + :param integer iyr: the year + :param integer idoy: the day of year (January 1st is `idoy=1`) + :param double UT: the time in seconds + :param array of 3 double xSM: cartesian position in SM (Re) + :output array of 3 double xGEO: cartesian position in GEO (Re) + :callseq MATLAB: xGEO = onera_desp_lib_rotate(xSM,'sm2geo',matlabd); + :callseq IDL: result = call_external(lib_name, 'sm2geo_', iyr,idoy,secs,xSM,xGEO, /f_value) + :callseq FORTRAN: call sm2geo1(iyr,idoy,secs,xSM,xGEO) + +.. irbem:routine:: GSM2SM + + Transforms :ref:`GSM ` to :ref:`SM ` coordinates. + + :param integer iyr: the year + :param integer idoy: the day of year (January 1st is `idoy=1`) + :param double UT: the time in seconds + :param array of 3 double xGSM: cartesian position in GSM (Re) + :output array of 3 double xSM: cartesian position in SM (Re) + :callseq MATLAB: xSM = onera_desp_lib_rotate(xGSM,'gsm2sm',matlabd); + :callseq IDL: result = call_external(lib_name, 'gsm2sm_', iyr,idoy,secs,xGSM,xSM, /f_value) + :callseq FORTRAN: call gsm2sm1(iyr,idoy,secs,xGSM,xSM) + +.. irbem:routine:: SM2GSM + + Transforms :ref:`SM ` to :ref:`GSM ` coordinates. + + :param integer iyr: the year + :param integer idoy: the day of year (January 1st is `idoy=1`) + :param double UT: the time in seconds + :param array of 3 double xSM: cartesian position in SM (Re) + :output array of 3 double xGSM: cartesian position in GSM (Re) + :callseq MATLAB: xGSM = onera_desp_lib_rotate(xSM,'sm2gsm',matlabd); + :callseq IDL: result = call_external(lib_name, 'sm2gsm_', iyr,idoy,secs,xSM,xGSM, /f_value) + :callseq FORTRAN: call sm2gsm1(iyr,idoy,secs,xSM,xGSM) + +.. irbem:routine:: GEO2MAG + + Transforms :ref:`GEO ` to :ref:`MAG ` coordinates. + + :param integer iyr: the year + :param array of 3 double xGEO: cartesian position in GEO (Re) + :output array of 3 double xMAG: cartesian position in MAG (Re) + :callseq MATLAB: xMAG = onera_desp_lib_rotate(xGEO,'geo2mag',matlabd); + :callseq IDL: result = call_external(lib_name, 'geo2mag_', iyr,idoy,secs,xGEO,xMAG, /f_value) + :callseq FORTRAN: call geo2mag1(iyr,xGEO,xMAG) + +.. irbem:routine:: MAG2GEO + + Transforms :ref:`MAG ` to :ref:`GEO ` coordinates. + + :param integer iyr: the year + :param integer idoy: the day of year (January 1st is `idoy=1`) + :param double UT: the time in seconds + :param array of 3 double xMAG: cartesian position in MAG (Re) + :output array of 3 double xGEO: cartesian position in GEO (Re) + :callseq MATLAB: xGEO = onera_desp_lib_rotate(xMAG,'mag2geo',matlabd); + :callseq IDL: result = call_external(lib_name, 'mag2geo_', iyr,idoy,secs,xMAG,xGEO, /f_value) + :callseq FORTRAN: call mag2geo1(iyr,xMAG,xGEO) + +.. irbem:routine:: SPH2CAR + + Routine to transform spherical coordinates to cartesian. + + :param double r: radial distance (arbitrary unit) + :param double lati: latitude (deg) + :param double longi: East longitude (deg) + :output array of 3 double x: cartesian coordinates (same unit as `r`) + :callseq MATLAB: xCAR = onera_desp_lib_rotate([r(:), lati(:), longi(:)],'sph2car'); + :callseq IDL: result = call_external(lib_name, 'sph2car_', r,lati,longi,x, /f_value) + :callseq FORTRAN: call SPH_CAR(r,lati,longi,x) + +.. irbem:routine:: CAR2SPH + + Routine to transform cartesian coordinates to spherical. + + :param array of 3 double x: cartesian coordinates (arbitrary unit) + :output double r: radial distance (same unit as `x`) + :output double lati: latitude (deg) + :output double longi: East longitude (deg) + :callseq MATLAB: xSPH = onera_desp_lib_rotate(xCAR,'car2sph'); + r = xSPH(:,1); lati = xSPH(:,2); longi = xSPH(:,3); + :callseq IDL: result = call_external(lib_name, 'car2sph_',x,r,lati,longi, /f_value) + :callseq FORTRAN: call CAR_SPH(x,r,lati,longi) + +.. irbem:routine:: RLL2GDZ + + Transforms :ref:`RLL ` to :ref:`GDZ ` + + :param double r: radial distance (Re) + :param double lati: latitude (deg) + :param double longi: East longitude (deg) + :output double alti: altitude (km) + :callseq MATLAB: xGDZ = onera_desp_lib_rotate([r(:), lati(:), longi(:)],'rll2gdz'); + alti = xGDZ(:,1); lati = xGDZ(:,2); longi = xGDZ(:,3); + :callseq IDL: result = call_external(lib_name, 'rll2gdz_', r,lati,longi,alti, /f_value) + :callseq FORTRAN: call RLL_GDZ(r,lati,longi,alti) + + +Geographic to heliospheric and vice versa coordinates transformations +--------------------------------------------------------------------- + +.. irbem:routine:: GSE2HEE + + Routine to transform geocentric coordinates GSE to heliospheric coordinates HEE + (Heliocentric Earth Ecliptic also sometime known as Heliospheric Solar Ecliptic + (HSE)). + + :param integer iyr: the year + :param integer idoy: the day of year (January 1st is `idoy=1`) + :param double UT: the time in seconds + :param array of 3 double xGSE: cartesian position in GSE (Re) + :output array of 3 double xHEE: cartesian position in HEE (AU) + :callseq MATLAB: xHEE = onera_desp_lib_rotate(xGSE,'gse2hee',matlabd); + :callseq IDL: result = call_external(lib_name, 'gse2hee_', iyr,idoy,UT,xGSE,xHEE, /f_value) + :callseq FORTRAN: call gse2hee1(iyr,idoy,UT,xGSE,xHEE) + +.. irbem:routine:: HEE2GSE + + Routine to transform heliospheric coordinates HEE (Heliocentric Earth + Ecliptic, also sometime known as Heliospheric Solar Ecliptic (HSE)) to + geocentric coordinates GSE. + + :param integer iyr: the year + :param integer idoy: the day of year (January 1st is `idoy=1`) + :param double UT: the time in seconds + :param array of 3 double xHEE: cartesian position in HEE (AU) + :output array of 3 double xGSE: cartesian position in GSE (Re) + :callseq MATLAB: xGSE = onera_desp_lib_rotate(xHEE,'hee2gse',matlabd); + :callseq IDL: result = call_external(lib_name, 'hee2gse_', iyr,idoy,UT,xHEE,xGSE, /f_value) + :callseq FORTRAN: call hee2gse1(iyr,idoy,UT,xHEE,xGSE) + + +Heliospheric coordinates transformations +---------------------------------------- + +.. irbem:routine:: HEE2HAE + + Routine to transform heliospheric coordinates HEE (Heliocentric Earth + Ecliptic also sometime known as Heliospheric Solar Ecliptic (HSE)) to + heliospheric coordinates HAE (Heliocentric Aries Ecliptic also sometime + known as Heliospheric Solar Ecliptic (HSE)) + + :param integer iyr: the year + :param integer idoy: the day of year (January 1st is `idoy=1`) + :param double UT: the time in seconds + :param array of 3 double xHEE: cartesian position in HEE (AU) + :output array of 3 double xHAE: cartesian position in HAE (AU) + :callseq MATLAB: onera_desp_lib_rotate(xHEE,'hee2hae',matlabd); + :callseq IDL: result = call_external(lib_name, 'hee2hae_', iyr,idoy,UT,xHEE,xHAE, /f_value) + :callseq FORTRAN: call hee2hae1(iyr,idoy,UT,xHEE,xHAE) + +.. irbem:routine:: HAE2HEE + + Routine to transform heliospheric coordinates HAE (Heliocentric Aries + Ecliptic also sometime known as Heliospheric Solar Ecliptic (HSE)) to + heliospheric coordinates HEE (Heliocentric Earth Ecliptic also sometime + known as Heliospheric Solar Ecliptic (HSE)) + + :param integer iyr: the year + :param integer idoy: the day of year (January 1st is `idoy=1`) + :param double UT: the time in seconds + :param array of 3 double xHAE: cartesian position in HAE (AU) + :output array of 3 double xHEE: cartesian position in HEE (AU) + :callseq MATLAB: xHEE = onera_desp_lib_rotate(xHAE,'hae2hee',matlabd); + :callseq IDL: result = call_external(lib_name, 'hae2hee_', iyr,idoy,UT,xHAE,xHEE, /f_value) + :callseq FORTRAN: call hae2hee1(iyr,idoy,UT,xHAE,xHEE) + +.. irbem:routine:: HAE2HEEQ + + Routine to transform heliospheric coordinates HAE (Heliocentric Aries + Ecliptic also sometime known as Heliospheric Solar Ecliptic (HSE)) to + heliospheric coordinates HEEQ (Heliocentric Earth Equatorial also + sometime known as Heliospheric Solar (HS)) + + :param integer iyr: the year + :param integer idoy: the day of year (January 1st is `idoy=1`) + :param double UT: the time in seconds + :param array of 3 double xHAE: cartesian position in HAE (AU) + :output array of 3 double xHEEQ: cartesian position in HEEQ (AU) + :callseq MATLAB: xHEEQ = onera_desp_lib_rotate(xHAE,'hae2heeq',matlabd); + :callseq IDL: result = call_external(lib_name, 'hae2heeq_', iyr,idoy,UT,xHAE,xHEEQ, /f_value) + :callseq FORTRAN: call hae2heeq1(iyr,idoy,UT,xHAE,xHEEQ) + + +.. irbem:routine:: HEEQ2HAE + + Routine to transform heliospheric coordinates HEEQ (Heliocentric Earth + Equatorial also sometime known as Heliospheric Solar (HS)) to heliospheric + coordinates HAE (Heliocentric Aries Ecliptic also sometime known as + Heliospheric Solar Ecliptic (HSE)) + + + :param integer iyr: the year + :param integer idoy: the day of year (January 1st is `idoy=1`) + :param double UT: the time in seconds + :param array of 3 double xHEEQ: cartesian position in HEEQ (AU) + :output array of 3 double xHAE: cartesian position in HAE (AU) + :callseq MATLAB: xHAE = onera_desp_lib_rotate(xHEEQ,'heeq2hae',matlabd); + :callseq IDL: result = call_external(lib_name, 'heeq2hae_', iyr,idoy,UT,xHEEQ,xHAE, /f_value) + :callseq FORTRAN: call heeq2hae1(iyr,idoy,UT,xHEEQ,xHAE) + diff --git a/docs/source/api/date_and_time.rst b/docs/source/api/date_and_time.rst new file mode 100644 index 00000000..df2878d7 --- /dev/null +++ b/docs/source/api/date_and_time.rst @@ -0,0 +1,76 @@ +Date and time functions +======================= + +.. irbem:routine:: JULDAY + + Calculate the Julian Day Number for a given month, day, and year. + + :param integer month: month number (1 = January, ..., 12 = December) + :param integer day: day of the month + :param integer year: year + :output integer julday: Julian Day Number which begins at noon of the specified calendar date + :callseq FORTRAN: result = JULDAY(year, month, day) + +.. irbem:routine:: CALDAT + + Return the calendar date given julian day. This is the inverse of the function :irbem:ref:`JULDAY`. + + :param integer julday: Julian Day Number + :output integer month: month number (1 = January, ..., 12 = December) + :output integer day: day of the month + :output integer year: year + :callseq FORTRAN: call CALDAT(julian, year, month, day) + +.. irbem:routine:: GET_DOY + + Calculate the day of year for a given month, day, and year. + + :param integer month: month number (1 = January, ..., 12 = December) + :param integer day: day of the month + :param integer year: year + :output integer doy: day of year + :callseq FORTRAN: doy = GET_DOY(year, month, day) + +.. irbem:routine:: DECY2DATE_AND_TIME + + Calculate the date and time (year, month, day of month, day of year and Universal Time) + + :param double dec_y: decimal year, where :code:`yyyy.0d0` is January 1st at 00:00 + :output integer year: year + :output integer month: month number (1 = January, ..., 12 = December) + :output integer day: day of the month + :output integer doy: day of year (1 for January 1st) + :output integer hour: UT hour of day (h) + :output integer minute: UT minute (min) + :output integer second: UT second (sec) + :output double UT: UT time of day (sec) + :callseq FORTRAN: CALL DECY2DATE_AND_TIME(Dec_y,Year,Month, Day, doy, hour,minute,second,UT) + +.. irbem:routine:: DATE_AND_TIME2DECY + + Calculate the decimal year from date and time. + + :param integer year: year + :param integer month: month number (1 = January, ..., 12 = December) + :param integer day: day of the month + :param integer hour: UT hour of day (h) + :param integer minute: UT minute (min) + :param integer second: UT second (sec) + :output double dec_y: decimal year, where :code:`yyyy.0d0` is January 1st at 00:00 + :callseq FORTRAN: CALL DATE_AND_TIME2DECY(Year,Month,Day,hour,minute,second,Dec_y) + +.. irbem:routine:: DOY_AND_UT2DATE_AND_TIME + + Calculate month, day, year, hour, minute, second from year, day of year and UT. + + :param integer year: year + :param integer doy: day of year (1 for January 1st) + :param double UT: UT time of day (sec) + :output integer month: month number (1 = January, ..., 12 = December) + :output integer day: day of the month + :output integer hour: UT hour of day (h) + :output integer minute: UT minute (min) + :output integer second: UT second (sec) + :callseq FORTRAN: CALL DOY_AND_UT2DATE_AND_TIME(Year,Doy,UT,Month, Day, hour,minute,second) + + diff --git a/docs/source/api/general_information.rst b/docs/source/api/general_information.rst new file mode 100644 index 00000000..cbb8f287 --- /dev/null +++ b/docs/source/api/general_information.rst @@ -0,0 +1,272 @@ +General information +=================== + +Data types +---------- + +Unless specified in this documentation, the IRBEM routines use 32 bits integers (also called long integer in IDL) and double-precision (64 bits) floating points numbers. All arrays are represented using the column-major ordering (as usual for Fortran libraries). + +.. _NALPHA_MAX: +.. _NENE_MAX: +.. _NTIME_MAX: + +Maximum array sizes +------------------- + +Some of the IRBEM routines can perform a particular calculation on multiple +points, for multiple energies or multiple pitch angles. For some of these +routines, there are limitations on the input and output array sizes, which +are defined throughout the library. + +Some routines have a maximum number of requested points, or use outputs arrays of +fixed size :code:`NTIME_MAX`. The value of :code:`NTIME_MAX` can be +retrieved using the :irbem:ref:`GET_IRBEM_NTIME_MAX` routine. + +Similarly, some routines impose maximum numbers of energy (:code:`NENE_MAX`) +and pitch angles (:code:`NALPHA_MAX`), which are defined as: + +.. code-block:: Fortran + + NENE_MAX = 25 + NALPHA_MAX = 25 + +.. _kext: + +External magnetic field model +----------------------------- + +IRBEM can compute magnetic coordinate and trace the field for various +magnetic field models from the litterature. Most routines +accept a :code:`kext` integer parameter which allows the selection of the +external magnetic field model, according to the following table: + +===== ================================================ ========== +Key Magnetic field name Comments +===== ================================================ ========== +0 No external field +1 Mead & Fairfield [1975] uses 0 ≤ Kp_ ≤ 9 - valid for rGEO ≤17 Re +2 Tsyganenko short [1987] uses 0 ≤ Kp_ ≤ 9 - valid for rGEO ≤30 Re +3 Tsyganenko long [1987] uses 0 ≤ Kp_ ≤ 9 - valid for rGEO ≤70 Re +4 Tsyganenko [1989c] uses 0 ≤ Kp_ ≤ 9 - valid for rGEO ≤70 Re +5 Olson & Pfitzer quiet [1977] valid for rGEO ≤15 Re +6 Olson & Pfitzer dynamic [1988] - uses 5 ≤ Dsw_ ≤ 50, 300 ≤ Vsw_ ≤ 500, -100 ≤ Dst_ ≤ 20 + - valid for rGEO ≤60 Re +7 Tsyganenko [1996] - uses -100 ≤ Dst_ ≤ 20, 0.5 ≤ Pdyn_ ≤ 10, \|\ By_\| ≤ 10, \|\ Bz_\| ≤ 10 + - valid for rGEO ≤40 Re +8 Ostapenko & Maltsev [1997] uses Dst_, Pdyn_, Bz_, Kp_ +9 Tsyganenko [2001] - uses -50 ≤ Dst_ ≤ 20, 0.5 ≤ Pdyn_ ≤ 5, \|\ By_\| ≤ 5, \|\ Bz_\| ≤ 5, 0 ≤ G1_ ≤ 10, 0 ≤ G2_ ≤ 10 + - valid for xGSM ≥-15 Re +10 Tsyganenko [2001] storm - uses Dst_, Pdyn_, By_, Bz_, G2_, G3_ + - there is no upper or lower limit for those inputs + - valid for xGSM ≥-15 Re +11 Tsyganenko [2004] storm - uses Dst_, Pdyn_, By_, Bz_, W1_, W2_, W3_, W4_, W5_, W6_ + - there is no upper or lower limit for those inputs + - valid for xGSM ≥-15 Re +12 Alexeev [2000], also known as Paraboloid model - uses Dsw_, Vsw_, Dst_, Bz_, AL_ +13 Tsyganenko [2007] +14 Mead-Tsyganenko - uses Kp_ + - onera model where the Tsyganenko 89 model is best fitted by a Mead model +===== ================================================ ========== + +.. note:: + + Besides the external field model, it is also possible to select the + internal magnetic field model used by IRBEM, using the 5th parameter in + the :ref:`options` array. + +.. _options: + +IRBEM options +------------- + +Some IRBEM routines accept an :code:`option` parameter, which is an array of 5 +integer flags allowing to control the behavior of the routines. + +.. list-table:: + :header-rows: 1 + + * - Index + - Quantity + - Values description + * - 1 + - L* or Φ + - - 0 - don't compute L* or Φ + - 1 - compute L* + - 2 - compute Φ + * - 2 + - IGRF Initialization + - - 0 - initialize IGRF field once per year (year.5) + - `n` - `n` is the frequency (in days) starting on January 1st of + each year (i.e. if options(2nd element)=15 then IGRF will be + updated on the following days of the year: 1, 15, 30, 45 ...) + * - 3 + - L* field line resolution + - 0-9, where 0 is the recommended value to ensure a good ratio + precision/computation time (i.e. an error of ~2% at L=6) - The higher + the value the better will be the precision, the longer will be the + computing time. Generally there is not much improvement for values + larger than 4. Note that this parameter defines the integration step + (θ) along the field line such as dθ=(π)/(720*[options(3rd + element)+1]) + * - 4 + - L* drift shell resolution + - 0-9 - The higher the value the better will be the precision, the longer + will be the computing time. It is recommended to use 0 (usually + sufficient) unless L* is not computed on a LEO orbit. For LEO orbit + higher values are recommended. Note that this parameter defines the + integration step (φ) along the drift shell such as + dφ=(2π)/(25*[options(4th element)+1]) + * - 5 + - Internal magnetic field selection + - - 0 - IGRF - default + - 1 - Eccentric tilted dipole + - 2 - Jensen & Cain 1960 + - 3 - GSFC 12/66 updated to 1970 + - 4 - User own magnetic field. The library then called a routine + which has to be written by the user + :code:`myOwnMagField(xGEO,Bxint)` where inputs are `xGEO` a double + array of 3 elements (x,y,z) containing geographic cartesian + coordinates in Re and outputs are `Bxint` a double array of 3 + elements (Bx,By,Bz) containing magnetic field components in + geographic cartesian coordinates in nT. + - 5 - Centered dipole + +.. todo give reference to magnetic fields + +.. _sysaxes: + +Coordinate systems +------------------ + +===== ========= ======================== +Key Name Description +===== ========= ======================== +0 _`GDZ` - Geodetic (altitude, latitude, East longitude) - km, deg, deg + - Defined using a reference ellipsoid. Geodetic longitude + is identical to `GEO`_ longitude. Both the altitude and + latitude depend on the ellipsoid used. IRBEM uses the + WGS84 reference ellipsoid. +1 _`GEO` - Geocentric geographic (cartesian) - Re + - Earth-Centered and Earth-Fixed. X lies in the + Earth's equatorial plane (zero latitude) and intersects + the Prime Meridian (zero longitude; Greenwich, UK). Z + points to True North (roughly aligned with the + instantaneous rotation axis). +2 _`GSM` - Geocentric Solar Magnetospheric (cartesian) - Re + - X points sunward from Earth's center. The X-Z plane is + defined to contain Earth's dipole axis (positive North). +3 _`GSE` - Geocentric Solar Ecliptic (cartesian) - Re + - X points sunward from Earth's center. Y lies in the + ecliptic plane of date, pointing in the anti-orbit + direction. Z is parallel to the ecliptic pole of date. +4 _`SM` - Solar Magnetic (cartesian) - Re + - Z is aligned with the centered dipole axis of date + (positive North), and Y is perpendicular to both the + Sun-Earth line and the dipole axis. X is therefore is + not aligned with the Sun-Earth line and `SM`_ is a rotation + about Y from `GSM`_. +5 _`GEI` - Geocentric Equatorial Inertial (cartesian) - Re + - X points from Earth toward the equinox of date (first + point of Aries; position of the Sun at the vernal + equinox). Z is parallel to the instantaneous rotation + axis of the Earth. +6 _`MAG` - Geomagnetic (cartesian) - Re + - Z is parallel to Earth's centered dipole axis (positive + North). Y is the intersection between Earth's equator + and the geographic meridian 90 degrees east of the + meridan containing the dipole axis. +7 _`SPH` - `GEO`_ in spherical (radial distance, latitude, East longitude) - Re, deg, deg + - Geoecentric geographic coordinates (`GEO`_ system) + expressed in spherical instead of Cartesian. +8 _`RLL` - Geodetic (radial distance, latitude, East longitude) - Re, deg, deg + - A re-expression of geodetic (`GDZ`_) coordinates using + radial distance instead of altitude above the reference + ellipsoid. Note that the latitude is still geodetic + latitude and is therefore not interchangeable with + `SPH`_. +9 _`HEE` - Heliocentric Earth Ecliptic (cartesian) - Re + - Origin is solar center; X points towards the Earth, and + Z is perpendicular to the plane of Earth's orbit + (positive North). This system is fixed with respect to + the Earth-Sun line. +10 _`HAE` - Heliocentric Aries Ecliptic (cartesian) - Re + - Origin is solar center. Z is perpendicular to the plane + of Earth's orbit (positive North) and X points towards + the equinox of date (first point of Aries). +11 _`HEEQ` - Heliocentric Earth Equatorial (cartesian) - Re + - Origin is solar center. Z is parallel to the Sun's + rotation axis (positive North) and X points towards the + intersection of the solar equator and solar central + meridian as seen from Earth. +12 _`TOD` - True of Date, same as `GEI`_ (cartesian) - Re + - This is the same as IRBEM's `GEI`_ and both are included + for legacy support. `TOD`_ uses the "true" (not mean) + equator of date and equinox of date to define the + coordinate system. +13 _`J2000` - `GEI`_ at J2000 (cartesian) - Re + - A key geocentric inertial frame. X is aligned with the + mean equinox at J2000; Z is parallel to the mean + rotation axis of the Earth at J2000 (that is, + perpendicular to the mean equator of J2000). The mean + equinox of date and mean equator of date (at any epoch) + correct only for precession, and not nutation. +14 _`TEME` - True Equator Mean Equinox (cartesian) - Re + - `TEME`_ is the inertial system used by the SGP4 orbit + propagator. +===== ========= ======================== + +.. note:: + + Four geocentric equatorial inertial systems are in widespread use. These + are J2000, MOD (Mean of Date), TOD, and TEME. J2000 defines the axes + using the equinox and pole at the J2000 epoch. Correcting for precession + transforms to MOD (which is identical to J2000 at 2000-01-01T11:58:55.816 + UTC), and then correcting for nutation tansforms to TOD (GEI). IRBEM + defines the geophysical systems (e.g., `GSE`_, `GSM`_, `SM`_) relative to TOD, + although some missions define these coordinate systems relative to a + different inertial reference system (usually MOD). + +.. note:: + + For details of the approximations used by IRBEM's coordinate + transformations, including the equation for estimating the Sun vector, + see (`Russel, 1971`_) and (`Hapgood, 1992`_). + +.. _Russel, 1971: http://jsoc.stanford.edu/~jsoc/keywords/Chris_Russel/Geophysical%20Coordinate%20Transformations.htm +.. _Hapgood, 1992: https://doi.org/10.1016/0032-0633(92)90012-D + +.. _maginput: + +Magnetic field inputs +--------------------- + +====== ========== ======================== +Index Name Description +====== ========== ======================== +1 _`Kp` value of Kp as in OMNI2 files but has to be double instead of integer type. (NOTE, consistent with OMNI2, this is Kp*10, and it is in the range 0 to 90) +2 _`Dst` Dst index (nT) +3 _`Dsw` solar wind density (cm\ :sup:`-3`) +4 _`Vsw` solar wind velocity (km/s) +5 _`Pdyn` solar wind dynamic pressure (nPa) +6 _`By` GSM y component of interplanetary magnetic field (nT) +7 _`Bz` GSM z component of interplanetary magnetic field (nT) +8 _`G1` <\ Vsw_ (Bperp/40)\ :sup:`2`/(1+Bperp/40) sin\ :sup:`3`\ (θ/2)> where the `<>` mean an average over the previous 1 hour, Bperp is the transverse IMF component (GSM) and θ its clock angle +9 _`G2` where Bs=|IMF Bz| when IMF Bz < 0 and Bs=0 when IMF Bz > 0, a=0.005 +10 _`G3` <\ Vsw_ Dsw_ Bs/2000> +11-16 _`W1` see definitions in (`Tsyganenko et al., 2005`_) + _`W2` + _`W3` + _`W4` + _`W5` + _`W6` +17 _`AL` auroral index +18-25 reserved for future use +====== ========== ======================== + +.. note:: + + Solar wind inputs must be taken in the vicinity of the day side + magnetopause and _not_ at L1. For instance, one can use the hourly NASA + OMNI2 dataset. + +.. _Tsyganenko et al., 2005: https://doi.org/10.1029/2004JA010798 diff --git a/docs/source/api/library_infos.rst b/docs/source/api/library_infos.rst new file mode 100644 index 00000000..ace8cff8 --- /dev/null +++ b/docs/source/api/library_infos.rst @@ -0,0 +1,49 @@ +Library information functions +============================= + +.. irbem:routine:: IRBEM_FORTRAN_VERSION + + Provides the repository version number of the fortran source code. + + :output integer VERSN: IRBEM version number + :callseq MATLAB: VERSN = onera_desp_lib_fortran_version + :callseq IDL: result = call_external(lib_name, 'irbem_fortran_version_',versn, /f_value) + :callseq FORTRAN: call IRBEM_FORTRAN_VERSION1(VERSN) + +.. irbem:routine:: IRBEM_FORTRAN_RELEASE + + Provides the repository release tag of the fortran source code. + + :output array of 80 characters RLS: release tag + :callseq MATLAB: RLS = onera_desp_lib_fortran_release + :callseq IDL: result = call_external(lib_name, 'irbem_fortran_release_', rls, /f_value) + :note: In IDL, string arguments should be defined as byte arrays, i.e.: :code:`rls = BYTARR(80)` + :callseq FORTRAN: call IRBEM_FORTRAN_RELEASE1(RLS) + +.. irbem:routine:: GET_IGRF_VERSION + + Returns the version number of the IGRF model. + + :output integer IGRF_VERSION: IGRF version number + :callseq MATLAB: igrf_version = onera_desp_lib_igrf_version + :callseq IDL: result = call_external(lib_name, 'igrf_version_idl_',igrf_version, /f_value) + :callseq FORTRAN: call GET_IGRF_VERION_(igrf_version) + +.. irbem:routine:: GET_IRBEM_NTIME_MAX + + Returns the size of time dimension in inputs and/or output arrays for some of the routines. + + .. note:: + In previous versions, the `ntime_max` parameter was used extensively in the IRBEM library. + + When possible (which is when the time dimension is the first dimension of the array), the + IRBEM routines now use variable-length array, so arbitrary array length can be provided, as + long as the array is big enough to contain the needed data (usually of size `ntime`). + + For routines where the `ntime_max` array size is still needed, it is explicitely mentioned + in the corresponding part of this documentation. + + :output integer NTIME_MAX: Time dimension size + :callseq MATLAB: ntime_max = onera_desp_lib_ntime_max + :callseq IDL: result = call_external(lib_name, 'get_irbem_ntime_max_',ntime_max, /f_value) + :callseq FORTRAN: call GET_IRBEM_NTIME_MAX1(ntime_max) diff --git a/docs/source/api/magnetic_coordinates.rst b/docs/source/api/magnetic_coordinates.rst new file mode 100644 index 00000000..3c841fd9 --- /dev/null +++ b/docs/source/api/magnetic_coordinates.rst @@ -0,0 +1,537 @@ +Magnetic coordinates and fields +=============================== + +Computing magnetic field coordinates +------------------------------------ + +The following routines compute magnetic coordinates for a given set of positions. The following coordinates are computed: + +* McIlwain Lm parameter +* Roederer L* parameter +* Φ coordinate (Φ=2π Bo/L*) +* magnetic field magnitude at the mirror point +* magnetic field magnitude at equator +* second invariant I parameter +* magnetic local time (MLT) + +Concerning the Lm and L* parameters, the IRBEM routines outputs also encodes whether local particles are trapped +or not - either because they don't belong to a closed drift shell, or because the drift shell intersects the atmosphere. +The coding of this information is presented in the following figure: + +.. _Lstar-coding: +.. figure:: Lstar.jpg + :width: 500px + + Coding of the Lm and L* parameters in IRBEM routines + +.. irbem:routine:: MAKE_LSTAR + + This function allows one to compute the magnetic coordinates at any spacecraft positions. + + A set of internal/external field can be selected. + + .. note:: + This routine computes the L* parameter for locally mirroring particles (local picth angle of 90 degrees). + See :irbem:ref:`MAKE_LSTAR_SHELL_SPLITTING` to compute L* for arbitrary pitch angles. + + .. note:: + For a fast approximation of this function for the Olson-Pfitzer Quiet + magnetic field model, see the :irbem:ref:`LANDI2LSTAR` routine. + + :param integer ntime: number of time points + :param integer kext: key for the :ref:`kext` + :param array of 5 integer options: :ref:`options` + :param integer sysaxes: key for the input coordinate system (see :ref:`sysaxes`) + :param array of `ntime` integer iyear: the year + :param array of `ntime` integer idoy: the day of year (January 1st is `idoy=1`) + :param array of `ntime` double UT: the time in seconds + :param array of `ntime` double x1: first coordinate according to `sysaxes` + :param array of `ntime` double x2: second coordinate according to `sysaxes` + :param array of `ntime` double x3: third coordinate according to `sysaxes` + :param array of [25, `ntime`] double maginput: :ref:`maginput` + :output array of `ntime` double Lm: L McIlwain - see :ref:`Lstar-coding` + :output array of `ntime` double Lstar: Roederer L* or Φ=2π Bo/L* (nT Re\ :sup:`2`), depending on the `options` value - for L*, see :ref:`Lstar-coding` + :output array of `ntime` double Blocal: magnitude of magnetic field at point (nT) + :output array of `ntime` double Bmin: magnitude of magnetic field at equator (nT) + :output array of `ntime` double XJ: I, related to second adiabatic invariant (Re) + :output array of `ntime` double MLT: magnetic local time (h) + :callseq MATLAB: [Lm,Lstar,Blocal,Bmin,J,MLT] = onera_desp_lib_make_lstar(kext,options,sysaxes,matlabd,x1,x2,x3,maginput) + :callseq IDL: result = call_external(lib_name, 'make_lstar_', ntime,kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3, maginput, lm,lstar,blocal,bmin,xj,mlt, /f_value) + :callseq FORTRAN: call make_lstar1(ntime,kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3, maginput, lm,lstar,blocal,bmin,xj,mlt) + :callseq Python: model = MagFields() + LLA = {'x1':651, 'x2':63, 'x3':20, 'dateTime':'2015-02-02T06:12:43'} + maginput = {'Kp':40} + output_dictionary = model.make_lstar(LLA, maginput) + +.. irbem:routine:: MAKE_LSTAR_SHELL_SPLITTING + + This function allows one to compute the magnetic coordinates at any spacecraft position and pitch-angle. + + A set of internal/external field can be selected. + + :param integer ntime: number of time points + :param integer npa: number of requested pitch angles, up to :code:`NALPHA_MAX` (see :ref:`NALPHA_MAX`) + :param integer kext: key for the :ref:`kext` + :param array of 5 integer options: :ref:`options` + :param integer sysaxes: key for the input coordinate system (see :ref:`sysaxes`) + :param array of `ntime` integer iyear: the year + :param array of `ntime` integer idoy: the day of year (January 1st is `idoy=1`) + :param array of `ntime` double UT: the time in seconds + :param array of `ntime` double x1: first coordinate according to `sysaxes` + :param array of `ntime` double x2: second coordinate according to `sysaxes` + :param array of `ntime` double x3: third coordinate according to `sysaxes` + :param array of `npa` double alpha: local pitch angles (deg) + :param array of [25, `ntime`] double maginput: :ref:`maginput` + :output array of [`ntime`, `NALPHA_MAX`] double Lm: L McIlwain - see :ref:`Lstar-coding` + :output array of [`ntime`, `NALPHA_MAX`] double Lstar: Roederer L* or Φ=2π Bo/L* (nT Re\ :sup:`2`), depending on the `options` value - for L*, see :ref:`Lstar-coding` + :output array of [`ntime`, `NALPHA_MAX`] double Bmirr: magnitude of magnetic field at mirror point (nT) + :output array of `ntime` double Bmin: magnitude of magnetic field at equator (nT) + :output array of [`ntime`, `NALPHA_MAX`] double XJ: I, related to second adiabatic invariant (Re) + :output array of `ntime` double MLT: magnetic local time (h) + :callseq MATLAB: [Lm,Lstar,Bmirror,Bmin,J,MLT] = onera_desp_lib_make_lstar_shell_splitting(kext,options,sysaxes,matlabd,x1,x2,x3,alpha,maginput) + :callseq IDL: result = call_external(lib_name, 'make_lstar_shell_splitting_', ntime,Npa,kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3,alpha,maginput,lm,lstar,bmirr,bmin,xj,mlt, /f_value) + :callseq FORTRAN: call make_lstar_shell_splitting1(ntime,Npa,kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3, alpha,maginput,lm,lstar,bmirr,bmin,xj,mlt) + +.. irbem:routine:: LANDI2LSTAR + + This function allows one to compute the magnetic coordinates at any spacecraft positions. + + This routine differs from :irbem:ref:`MAKE_LSTAR` because L* is deduced from + Lm, I and day of year empirically, which is much faster. This is set only + for IGRF+Olson-Pfitzer quiet field model (:code:`kext` can only be 5). The errors in + L* values are less than 2%. + + .. note:: + This routine computes the L* parameter for locally mirroring particles (local picth angle of 90 degrees). + See :irbem:ref:`LANDI2LSTAR_SHELL_SPLITTING` to compute L* for arbitrary pitch angles. + + :param integer ntime: number of time points + :param integer kext: key for the :ref:`kext` + :param array of 5 integer options: :ref:`options` + :param integer sysaxes: key for the input coordinate system (see :ref:`sysaxes`) + :param array of `ntime` integer iyear: the year + :param array of `ntime` integer idoy: the day of year (January 1st is `idoy=1`) + :param array of `ntime` double UT: the time in seconds + :param array of `ntime` double x1: first coordinate according to `sysaxes` + :param array of `ntime` double x2: second coordinate according to `sysaxes` + :param array of `ntime` double x3: third coordinate according to `sysaxes` + :param array of [25, `ntime`] double maginput: :ref:`maginput` + :output array of `ntime` double Lm: L McIlwain - see :ref:`Lstar-coding` + :output array of `ntime` double Lstar: Roederer L* or Φ=2π Bo/L* (nT Re\ :sup:`2`), depending on the `options` value - for L*, see :ref:`Lstar-coding` + :output array of `ntime` double Blocal: magnitude of magnetic field at point (nT) + :output array of `ntime` double Bmin: magnitude of magnetic field at equator (nT) + :output array of `ntime` double XJ: I, related to second adiabatic invariant (Re) + :output array of `ntime` double MLT: magnetic local time (h) + :callseq MATLAB: [Lm,Lstar,Blocal,Bmin,J,MLT] = onera_desp_lib_landi2lstar(kext,options,sysaxes,matlabd,x1,x2,x3,maginput) + :callseq IDL: result = call_external(lib_name, 'landi2lstar_', ntime,kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3, maginput, lm,lstar,blocal,bmin,xj,mlt, /f_value) + :callseq FORTRAN: call landi2lstar1(ntime,kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3, maginput, lm,lstar,blocal,bmin,xj,mlt) + +.. irbem:routine:: LANDI2LSTAR_SHELL_SPLITTING + + This function allows one to compute the magnetic coordinates at any spacecraft position and pitch-angle. + + This routine differs from :irbem:ref:`MAKE_LSTAR_SHELL_SPLITTING` because L* is deduced from + Lm, I and day of year empirically, which is much faster. This is set only + for IGRF+Olson-Pfitzer quiet field model (:code:`kext` can only be 5). The errors in + L* values are less than 2%. + + :param integer ntime: number of time points + :param integer npa: number of requested pitch angles, up to :code:`NALPHA_MAX` (see :ref:`NALPHA_MAX`) + :param integer kext: key for the :ref:`kext` + :param array of 5 integer options: :ref:`options` + :param integer sysaxes: key for the input coordinate system (see :ref:`sysaxes`) + :param array of `ntime` integer iyear: the year + :param array of `ntime` integer idoy: the day of year (January 1st is `idoy=1`) + :param array of `ntime` double UT: the time in seconds + :param array of `ntime` double x1: first coordinate according to `sysaxes` + :param array of `ntime` double x2: second coordinate according to `sysaxes` + :param array of `ntime` double x3: third coordinate according to `sysaxes` + :param array of `npa` double alpha: local pitch angles (deg) + :param array of [25, `ntime`] double maginput: :ref:`maginput` + :output array of [`ntime`, `NALPHA_MAX`] double Lm: L McIlwain - see :ref:`Lstar-coding` + :output array of [`ntime`, `NALPHA_MAX`] double Lstar: Roederer L* or Φ=2π Bo/L* (nT Re\ :sup:`2`), depending on the `options` value - for L*, see :ref:`Lstar-coding` + :output array of [`ntime`, `NALPHA_MAX`] double Bmirr: magnitude of magnetic field at mirror point (nT) + :output array of `ntime` double Bmin: magnitude of magnetic field at equator (nT) + :output array of [`ntime`, `NALPHA_MAX`] double XJ: I, related to second adiabatic invariant (Re) + :output array of `ntime` double MLT: magnetic local time (h) + :callseq MATLAB: [Lm,Lstar,Bmirror,Bmin,J,MLT] = onera_desp_lib_landi2lstar_shell_splitting(kext,options,sysaxes,matlabd,x1,x2,x3,alpha,maginput) + :callseq IDL: result = call_external(lib_name, 'landi2lstar_shell_splitting_', ntime,Npa,kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3,alpha,maginput,lm,lstar,blocal,bmin,xj,mlt, /f_value) + :callseq FORTRAN: call landi2lstar_shell_splitting1(ntime,Npa,kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3, alpha,maginput,lm,lstar,blocal,bmin,xj,mlt) + +.. irbem:routine:: EMPIRICALLSTAR + + This function allows one to compute L* empirically being given Lm, I and + day of year. This is set only for IGRF+Olson-Pfitzer quiet field model + (:code:`kext` can only be 5) so Lm and I provided as input must be computed with + this field. The errors in L* values are less than 2%. + + :param integer ntime: number of time points + :param integer kext: key for the :ref:`kext` + :param array of 5 integer options: :ref:`options` + :param array of `ntime` integer iyear: the year + :param array of `ntime` integer idoy: the day of year (January 1st is `idoy=1`) + :param array of [25, `ntime`] double maginput: :ref:`maginput` + :param array of `ntime` double Lm: L McIlwain + :param array of `ntime` double XJ: I, related to second adiabatic invariant (Re) + :output array of `ntime` double Lstar: L Roederer or Φ=2π Bo/L* (nT Re\ :sup:`2`), depending on the `options` value + :callseq MATLAB: Lstar = onera_desp_lib_empiricallstar(kext,options,matlabd,maginput,Lm,J) + :callseq IDL: result = call_external(lib_name, 'empiricalLstar_', ntime,kext,options,iyearsat,idoy, maginput, lm,xj,lstar, /f_value) + :callseq FORTRAN: call EmpiricalLstar1(ntime,kext,options,iyearsat,idoy,maginput, lm,xj,lstar) + +.. irbem:routine:: GET_MLT + + Routine to get Magnetic Local Time (MLT) from a :ref:`GEO ` position and date. + + :param integer iyear: the year + :param integer idoy: the day of year (January 1st is `idoy=1`) + :param double secs: the time in seconds + :param array of 3 double xGEO: cartesian position in :ref:`GEO ` + :output double MLT: Magnetic Local Time (h) + :callseq MATLAB: MLT = onera_desp_lib_get_mlt(matlabd,xGEO) + :callseq IDL: result = call_external(lib_name, 'get_mlt_', iyr,idoy,secs,xGEO,MLT, /f_value) + :callseq FORTRAN: call get_mlt1(iyr,idoy,secs,xGEO,MLT) + +.. irbem:routine:: GET_HEMI_MULTI + + This function computes in which magnetic hemisphere is the input location. + + :param integer ntime: number of time points + :param integer kext: key for the :ref:`kext` + :param array of 5 integer options: :ref:`options` + :param integer sysaxes: key for the input coordinate system (see :ref:`sysaxes`) + :param array of `ntime` integer iyear: the year + :param array of `ntime` integer idoy: the day of year (January 1st is `idoy=1`) + :param array of `ntime` double UT: the time in seconds + :param array of `ntime` double x1: first coordinate according to `sysaxes` + :param array of `ntime` double x2: second coordinate according to `sysaxes` + :param array of `ntime` double x3: third coordinate according to `sysaxes` + :param array of [25, `ntime`] double maginput: :ref:`maginput` + :output array of `ntime` integer xHEMI: +1 for Northern magnetic hemisphere, -1 for Southern magnetic hemisphere, 0 for invalid magnetic field + :callseq MATLAB: [xHEMI] = onera_desp_lib_get_hemi(kext,options,sysaxes,matlabd,x1,x2,x3,maginput) + :callseq IDL: result = call_external(lib_name, 'get_hemi_multi_idl_',ntime,kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3, maginput,xHEMI, /f_value) + :callseq FORTRAN: call GET_HEMI_MULTI(ntime,kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3, maginput,xHEMI) + +.. irbem:routine:: LSTAR_PHI + + Converts from L* to Φ or vice versa. + + Φ=2π*Bo/L* + + :param integer ntime: number of time points + :param integer whichinv: direction of the transformation: 1 for L* to Φ, 2 for Φ to L* + :param array of 5 integer options: :ref:`options` + :param array of `ntime` integer iyear: the year + :param array of `ntime` integer idoy: the day of year (January 1st is `idoy=1`) + :output array of `ntime` double Lstar: L* (input or output depending on `whichinv` value) + :output array of `ntime` double Phi: Φ (nT Re\ :sup:`2`,input or output depending on `whichinv` value) + :callseq MATLAB: out = onera_desp_lib_lstar_phi(which,options,matlabd,in) + :callseq IDL: result = call_external(lib_name, lstar_phi_', ntime,whichinv,options,iyear,idoy,lstar,phi, /f_value) + :callseq FORTRAN: call lstar_phi1(ntime,whichinv,options,iyear,idoy,lstar,phi) + +Points of interest on the field line +------------------------------------ + +.. irbem:routine:: FIND_MIRROR_POINT + + This function finds the magnitude and location of the mirror point along + a field line traced from any given location and local pitch-angle for a set of internal/external field to be selected. + + :param integer kext: key for the :ref:`kext` + :param array of 5 integer options: :ref:`options` + :param integer sysaxes: key for the input coordinate system (see :ref:`sysaxes`) + :param integer iyear: the year + :param integer idoy: the day of year (January 1st is `idoy=1`) + :param double UT: the time in seconds + :param double x1: first coordinate according to `sysaxes` + :param double x2: second coordinate according to `sysaxes` + :param double x3: third coordinate according to `sysaxes` + :param double alpha: local pitch-angle (deg) + :param array of 25 double maginput: :ref:`maginput` + :output double Blocal: magnitude of magnetic field at point (nT) + :output double Bmirr: magnitude of the magnetic field at the mirror point (nT) + :output array of 3 double POSIT: :ref:`GEO ` coordinates of the mirror point (Re) + :callseq MATLAB: [Blocal,Bmirror,xGEO] = onera_desp_lib_find_mirror_point(kext,options,sysaxes,matlabd,x1,x2,x3,alpha,maginput) + :callseq IDL: result = call_external(lib_name, 'find_mirror_point_', kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3,alpha,maginput, blocal,bmir,posit, /f_value) + :callseq FORTRAN: call find_mirror_point1(kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3,alpha, maginput,blocal,bmir,posit) + :callseq Python: model = MagFields() + LLA = {'x1':651, 'x2':63, 'x3':20, 'dateTime':'2015-02-02T06:12:43'} + maginput = {'Kp':40} + alpha = 90 + output_dictionary = model.find_mirror_point(LLA, maginput, alpha) + +.. irbem:routine:: FIND_MAGEQUATOR + + This function finds the GEO coordinates of the magnetic equator along the field line + starting from input location for a set of internal/external field to be selected. + + :param integer kext: key for the :ref:`kext` + :param array of 5 integer options: :ref:`options` + :param integer sysaxes: key for the input coordinate system (see :ref:`sysaxes`) + :param integer iyear: the year + :param integer idoy: the day of year (January 1st is `idoy=1`) + :param double UT: the time in seconds + :param double x1: first coordinate according to `sysaxes` + :param double x2: second coordinate according to `sysaxes` + :param double x3: third coordinate according to `sysaxes` + :param array of 25 double maginput: :ref:`maginput` + :output double Bmin: magnitude of magnetic field at equator (nT) + :output array of 3 double POSIT: :ref:`GEO ` coordinates of the magnetic equator (Re) + :callseq MATLAB: [Bmin,xGEO] = onera_desp_lib_find_magequator(kext,options,sysaxes,matlabd,x1,x2,x3,maginput) + :callseq IDL: result = call_external(lib_name, 'find_magequator_', kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3, maginput, bmin,posit, /f_value) + :callseq FORTRAN: call find_magequator1(kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3, maginput,bmin,posit) + :callseq Python: model = MagFields() + LLA = {'x1':651, 'x2':63, 'x3':20, 'dateTime':'2015-02-02T06:12:43'} + maginput = {'Kp':40} + alpha = 90 + output_dictionary = model.find_magequator(LLA, maginput) + +.. irbem:routine:: FIND_FOOT_POINT + + This function finds the of the field line crossing a specified altitude in a specified hemisphere + for a set of internal/external field to be selected. + + :param integer kext: key for the :ref:`kext` + :param array of 5 integer options: :ref:`options` + :param integer sysaxes: key for the input coordinate system (see :ref:`sysaxes`) + :param integer iyear: the year + :param integer idoy: the day of year (January 1st is `idoy=1`) + :param double UT: the time in seconds + :param double x1: first coordinate according to `sysaxes` + :param double x2: second coordinate according to `sysaxes` + :param double x3: third coordinate according to `sysaxes` + :param double stop_alt: desired altitude of field-line crossing (km) + :param integer hemi_flag: key to select the magnetic hemisphere: + * 0 - Same magnetic hemisphere as starting point + * +1 - northern magnetic hemisphere + * -1 - southern magnetic hemisphere + * +2 - opposite magnetic hemisphere from starting point + :param array of 25 double maginput: :ref:`maginput` + :output array of 3 double XFOOT: :ref:`GDZ ` coordinates of the foot point (Re) + :output array of 3 double BFOOT: magnetic field vector (:ref:`GEO `) at the foot point (nT) + :output double BFOOTMAG: magnitude of the magnetic field at the foot point (nT) + :callseq MATLAB: [Xfoot,Bfoot,BfootMag] = onera_desp_lib_find_foot_point(kext,options,sysaxes,matlabd,x1,x2,x3,stop_alt,hemi_flag,maginput) + :callseq IDL: result = call_external(lib_name, 'find_foot_point_', kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3,stop_alt,hemi_flag,maginput, xfoot,bfoot,bfootmag, /f_value) + :callseq FORTRAN: call find_foot_point1(kext,options,sysaxes,iyearsat,idoy,UT,xIN1,xIN2,xIN3,stop_alt,hemi_flag,maginput,XFOOT,BFOOT,BFOOTMAG) + :callseq Python: model = MagFields() + LLA = {'x1':651, 'x2':63, 'x3':20, 'dateTime':'2015-02-02T06:12:43'} + maginput = {'Kp':40} + stopAlt = 100 + hemiFlag = 0 + output_dictionary = model.find_foot_point(LLA, maginput, stopAlt, hemiFlag) + +Magnetic field computation +-------------------------- + +.. irbem:routine:: GET_FIELD_MULTI + + This function computes the magnetic field vector (expressed in the :ref:`GEO ` + coordinate system) at the input locations using the selected + internal and external magnetic field models. + + :param integer ntime: number of time points + :param integer kext: key for the :ref:`kext` + :param array of 5 integer options: :ref:`options` + :param integer sysaxes: key for the input coordinate system (see :ref:`sysaxes`) + :param array of `ntime` integer iyear: the year + :param array of `ntime` integer idoy: the day of year (January 1st is `idoy=1`) + :param array of `ntime` double UT: the time in seconds + :param array of `ntime` double x1: first coordinate according to `sysaxes` + :param array of `ntime` double x2: second coordinate according to `sysaxes` + :param array of `ntime` double x3: third coordinate according to `sysaxes` + :param array of [25, `ntime`] double maginput: :ref:`maginput` + :output array of [3, `ntime`] double Bgeo: `BxGEO`, `ByGEO`, `BzGEO` of the magnetic field (nT) + :output array of `ntime` double Bl: magnitude of the magnetic field (nT) + :callseq MATLAB: [Bgeo,B] = onera_desp_lib_get_field(kext,options,sysaxes,matlabd,x1,x2,x3,maginput) + :callseq IDL: result = call_external(lib_name, 'get_field_multi_idl_',ntime,kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3, maginput,Bgeo, Bl, /f_value) + :callseq FORTRAN: call GET_FIELD_MULTI(ntime,kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3, maginput,Bgeo,Bl) + :callseq Python: model = MagFields() + LLA = {'x1':651, 'x2':63, 'x3':20, 'dateTime':'2015-02-02T06:12:43'} + maginput = {'Kp':40} + output_dictionary = model.get_field_multi(LLA, maginput) + + +.. irbem:routine:: GET_BDERIVS + + This function computes the magnetic field and its 1st-order derivatives at + each input location for a set of internal/external magnetic field to be + selected. + + :param integer ntime: number of time points up to :code:`NTIME_MAX` (see :ref:`NTIME_MAX`) + :param integer kext: key for the :ref:`kext` + :param array of 5 integer options: :ref:`options` + :param integer sysaxes: key for the input coordinate system (see :ref:`sysaxes`) + :param double dX: step size for the numerical derivatives (Re) + :param array of `ntime` integer iyear: the year + :param array of `ntime` integer idoy: the day of year (January 1st is `idoy=1`) + :param array of `ntime` double UT: the time in seconds + :param array of `ntime` double x1: first coordinate according to `sysaxes` + :param array of `ntime` double x2: second coordinate according to `sysaxes` + :param array of `ntime` double x3: third coordinate according to `sysaxes` + :param array of [25, `ntime`] double maginput: :ref:`maginput` + :output array of [3, `ntime`] double Bgeo: `BxGEO`, `ByGEO`, `BzGEO` of the magnetic field (nT) + :output array of `ntime` double Bmag: magnitude of the magnetic field (nT) + :output array of [3, `ntime`] double gradBmag: gradients of `Bmag` in :ref:`GEO ` (nT) + :output array of [3, 3, `ntime`] double diffB: derivatives of the magnetic field vector (nT) for the n\ :sup:`th` point, `diffB(i,j,n)` = dB\ :sub:`i` / dx\ :sub:`j` + :callseq MATLAB: [Bgeo,B,gradBmag,diffB] = onera_desp_lib_get_bderivs(kext,options,sysaxes,matlabd,x1,x2,x3,maginput) + :callseq IDL: result = call_external(lib_name, 'get_bderivs_idl',ntime,kext,options,sysaxes,dX,iyear,idoy,ut, x1,x2,x3, maginput,Bgeo,Bmag,gradBmag,diffB, /f_value) + :callseq FORTRAN: call GET_BDERIVS(ntime,kext,options,sysaxes,dX,iyear,idoy,ut, x1,x2,x3, maginput,Bgeo,Bmag,gradBmag,diffB) + +.. irbem:routine:: COMPUTE_GRAD_CURV_CURL + + This function computes gradient and curvature force factors and div/curl of + B from the outputs of :irbem:ref:`GET_BDERIVS`. + + :param integer ntime: number of time points + :param array of [3, `ntime`] double Bgeo: `BxGEO`, `ByGEO`, `BzGEO` of the magnetic field (nT) + :param array of `ntime` double Bmag: magnitude of the magnetic field (nT) + :param array of [3, `ntime`] double gradBmag: gradients of `Bmag` in :ref:`GEO ` (nT) + :param array of [3, 3, `ntime`] double diffB: derivatives of the magnetic field vector (nT) + :output array of `ntime` double grad_par: gradient of Bmag along Bgeo (nT/Re) + :output array of [3, `ntime`] double grad_perp: gradient of Bmag perpendicular to B (nT/Re) + :output array of [3, `ntime`] double grad_drift: (Bhat x grad_perp)/Bmag, with Bhat=Bgeo/Bmag part of gradient drift velocity (1/Re) + :output array of [3, `ntime`] double curvature: (Bhat . grad)Bhat, part of curvature force, (1/Re) + :output array of `ntime` double Rcurv: 1/\|curvature\|, radius of curvature (Re) + :output array of [3, `ntime`] double curv_drift: Bhat x curvature, part of curvature drift (1/Re) + :output array of [3, `ntime`] double curlB: curl of B, part of electrostatic current term (nT/Re) + :output array of `ntime` double divB: divergence of B, should be zero (nT/Re) + :callseq MATLAB: [grad_par,grad_perp,grad_drift,curvature,Rcurv,curv_drift,curlB,divB] = onera_desp_lib_compute_grad_curv_curl(Bgeo,B,gradBmag,diffB) + :callseq IDL: result = call_external(lib_name, 'compute_grad_curv_idl',ntime,Bgeo,Bmag,gradBmag,diffB, grad_par,grad_perp,grad_drift,curvature,Rcurv,curv_drift,curlB,divB, /f_value) + :callseq FORTRAN: call COMPUTE_GRAD_CURV_CURL(ntime,Bgeo,Bmag,gradBmag,diffB, grad_par,grad_perp,grad_drift,curvature,Rcurv,curv_drift,curlB,divB) + +Field tracing +------------- + +.. irbem:routine:: TRACE_FIELD_LINE + + This function traces a full field line which crosses the input position. The + output is a full array of positions of the field line. + + :param integer kext: key for the :ref:`kext` + :param array of 5 integer options: :ref:`options` + :param integer sysaxes: key for the input coordinate system (see :ref:`sysaxes`) + :param integer iyear: the year + :param integer idoy: the day of year (January 1st is `idoy=1`) + :param double UT: the time in seconds + :param double x1: first coordinate according to `sysaxes` + :param double x2: second coordinate according to `sysaxes` + :param double x3: third coordinate according to `sysaxes` + :param array of 25 double maginput: :ref:`maginput` + :param double R0: radius of the reference surface between which field line is traced (Re) + :output double Lm: L McIlwain + :output array of 3000 double Blocal: magnitude of magnetic field at point (nT) + :output double Bmin: magnitude of magnetic field at equator (nT) + :output double XJ: I, related to second adiabatic invariant (Re) + :output array of (3, 3000) double posit: Cartesian coordinates in :ref:`GEO ` along the field line + :output integer Nposit: number of points in `posit` + :callseq MATLAB: [Lm,Blocal,Bmin,J,POSIT] = onera_desp_lib_trace_field_line(kext,options,sysaxes,matlabd,x1,x2,x3,maginput,R0) + :callseq IDL: result = call_external(lib_name, 'trace_field_line2_', kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3,maginput,R0,lm,blocal,bmin,xj,posit,Nposit, /f_value) + :callseq FORTRAN: call trace_field_line2_1(kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3, maginput,R0, lm,blocal,bmin,xj,posit,Nposit) + :callseq Python: model = MagFields() + LLA = {'x1':651, 'x2':63, 'x3':20, 'dateTime':'2015-02-02T06:12:43'} + maginput = {'Kp':40} + output_dictionary = model.trace_field_line(LLA, maginput) + +.. irbem:routine:: TRACE_FIELD_LINE_TOWARD_EARTH + + This function traces a field line from the input position to the Earth + surface. The output is a full array of positions of the field line, usefull + for plotting and visualisation. + + :param integer kext: key for the :ref:`kext` + :param array of 5 integer options: :ref:`options` + :param integer sysaxes: key for the input coordinate system (see :ref:`sysaxes`) + :param integer iyear: the year + :param integer idoy: the day of year (January 1st is `idoy=1`) + :param double UT: the time in seconds + :param double x1: first coordinate according to `sysaxes` + :param double x2: second coordinate according to `sysaxes` + :param double x3: third coordinate according to `sysaxes` + :param array of 25 double maginput: :ref:`maginput` + :param double ds: integration step along the field line (Re) + :output array of (3, 3000) double posit: Cartesian coordinates in :ref:`GEO ` along the field line + :output integer Nposit: number of points in `posit` + :callseq MATLAB: POSIT = onera_desp_lib_trace_field_line_towards_earth(kext,options,sysaxes,matlabd,x1,x2,x3,maginput,ds) + :callseq IDL: result = call_external(lib_name, 'trace_field_line_towards_earth_', kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3, maginput, ds,posit,Nposit, /f_value) + :callseq FORTRAN: call trace_field_line_towards_earth1(kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3, maginput, ds,posit,Nposit) + + +.. irbem:routine:: DRIFT_BOUNCE_ORBIT + + This function traces a full drift shell for particles that have their + mirror point at the input location. The output is a full array of + positions of the drift shell, usefull for plotting and visualisation. + + Key differences from :irbem:ref:`DRIFT_SHELL` : + + * only positions between mirror points are returned + * 25 - rather than 48 - azimuths are returned + * Lstar accuracy respects :code:`options(3)` and :code:`options(4)` (see :ref:`options`) + * a new parameter :code:`R0` is required which specifies the minimum radial + distance allowed along the drift path (usually `R0` = 1, but use `R0` < 1 in the + drift loss cone) + * :code:`hmin` and :code:`hmin_lon` outputs provide the altitude and + longitude (in :ref:`GDZ `) of the minimum altitude point along the drift + shell (among those traced, not just those returned). + + :param integer kext: key for the :ref:`kext` + :param array of 5 integer options: :ref:`options` + :param integer sysaxes: key for the input coordinate system (see :ref:`sysaxes`) + :param integer iyear: the year + :param integer idoy: the day of year (January 1st is `idoy=1`) + :param double UT: the time in seconds + :param double x1: first coordinate according to `sysaxes` + :param double x2: second coordinate according to `sysaxes` + :param double x3: third coordinate according to `sysaxes` + :param double alpha: pitch angle at input location (deg) + :param array of 25 double maginput: :ref:`maginput` + :param double R0: radius of the minimum allowed radial distance along the drift orbit (Re) + :output double Lm: L McIlwain + :output double Lstar: L Roederer or Φ=2π Bo/L* (nT Re\ :sup:`2`), depending on the `options` value + :output array of (1000, 25) double Blocal: magnitude of magnetic field at point (nT) + :output double Bmin: magnitude of magnetic field at equator (nT) + :output double XJ: I, related to second adiabatic invariant (Re) + :output array of (3, 1000, 25) double posit: Cartesian coordinates in :ref:`GEO ` along the drift shell + :output array of 25 integer Nposit: number of points in `posit` along each traced field line + :callseq MATLAB: [Lm,Lstar,Blocal,Bmin,Bmir,J,POSIT,hmin,hmin_lon] = onera_desp_lib_drift_bounce_orbit(kext,options,sysaxes,matlabd,x1,x2,x3,alpha,maginput,R0) + :callseq IDL: result = call_external(lib_name, 'drift_bounce_orbit2_', kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3,alpha, maginput,R0, lm,lstar,blocal,bmin,bmir,xj,posit,Nposit,hmin,hmin_lon, /f_value) + :callseq FORTRAN: call drift_bounce_orbit2_1(kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3,alpha, maginput,R0 lm,lstar,blocal,bmin,bmir,xj,posit,Nposit,hmin,hmin_lon) + :callseq Python: model = MagFields() + LLA = {'x1':651, 'x2':63, 'x3':20, 'dateTime':'2015-02-02T06:12:43'} + maginput = {'Kp':40} + output_dictionary = model.drift_bounce_orbit(LLA, maginput) + +.. irbem:routine:: DRIFT_SHELL + + This function traces a full drift shell for particles that have their + mirror point at the input location. The output is a full array of + positions of the drift shell, usefull for plotting and visualisation. + + .. note:: + + To only get the points on the drift-bounce orbit, use :irbem:ref:`DRIFT_BOUNCE_ORBIT`. + + :param integer kext: key for the :ref:`kext` + :param array of 5 integer options: :ref:`options` + :param integer sysaxes: key for the input coordinate system (see :ref:`sysaxes`) + :param integer iyear: the year + :param integer idoy: the day of year (January 1st is `idoy=1`) + :param double UT: the time in seconds + :param double x1: first coordinate according to `sysaxes` + :param double x2: second coordinate according to `sysaxes` + :param double x3: third coordinate according to `sysaxes` + :param array of 25 double maginput: :ref:`maginput` + :output double Lm: L McIlwain + :output double Lstar: L Roederer or Φ=2π Bo/L* (nT Re\ :sup:`2`), depending on the `options` value + :output array of (1000, 48) double Blocal: magnitude of magnetic field at point (nT) + :output double Bmin: magnitude of magnetic field at equator (nT) + :output double XJ: I, related to second adiabatic invariant (Re) + :output array of (3, 1000, 48) double posit: Cartesian coordinates in :ref:`GEO ` along the drift shell + :output array of 48 integer Nposit: number of points in `posit` along each traced field line + :callseq MATLAB: [Lm,Lstar,Blocal,Bmin,J,POSIT] = onera_desp_lib_drift_shell(kext,options,sysaxes,matlabd,x1,x2,x3,maginput) + :callseq IDL: result = call_external(lib_name, 'drift_shell_', kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3, maginput, lm,lstar,blocal,bmin,xj,posit,Nposit, /f_value) + :callseq FORTRAN: call drift_shell1(kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3, maginput, lm,lstar,blocal,bmin,xj,posit,Nposit) + :callseq Python: model = MagFields() + LLA = {'x1':651, 'x2':63, 'x3':20, 'dateTime':'2015-02-02T06:12:43'} + maginput = {'Kp':40} + output_dictionary = model.drift_shell(LLA, maginput) + diff --git a/docs/source/api/orbit_propagation.rst b/docs/source/api/orbit_propagation.rst new file mode 100644 index 00000000..92f08d59 --- /dev/null +++ b/docs/source/api/orbit_propagation.rst @@ -0,0 +1,205 @@ +Orbit propagation +================= + +.. irbem:routine:: SGP4_TLE + + Propagates NORAD Two-Lines Elements and compute the spacecraft position. + + SGP4 stands for Simplified General Perturbation -4 and consists in an orbit + propagator. This function allows one to propagate NORAD two lines elements + (TLE sets can be found at http://celestrak.com/). More about SGP4 can be + found at http://celestrak.com/NORAD/documentation/spacetrk.pdf . + + .. important:: + + Those who are running the library on Unix or linux system + have to convert TLE files from NORAD from DOS to UNIX using the command + :code:`dos2unix file.tle newfile.tle`. Also be aware that some TLE files + contains random errors, like elements from another satellite, repeated + elements, ... there are no specific filters implemented in the SGP4 + function. + + For those who are familiar with SGP4 code, be aware for one difference + between orginal SGP4 code and the one provided here: input start and stop + time and time step are not in minutes but in seconds. This was chosen for + convenience. + + :param integer runtype: key to select the SGP4_TLE mode: + + 0. defines start and stop time to propagate each TLE according to input file + 1. propagates each TLE according to user start and stop time + + :param double startsfe: start time from date provided in each TLE (s) - can be negative, ignored for `runtype = 0` + :param double stopsfe: stop time from date provided in each TLE (s) - can be negative, ignored for `runtype = 0` + :param double deltasec: step time to propagate TLE (s) + :param byte array InFileByte: path and name of the input TLE file to be propagated + :param integer strlenIn: length of `InFileByte` string + :param byte array OutFileByte: path and name of the output file + :param integer strlenOut: length of `OutFileByte` string + :output file: The output file is composed of 6 columns: + + 1. date (dd/mm/yyyy) + 2. time (hh:mm:ss) + 3. decimal year + 4. altitude (km) + 5. latitude (deg) + 6. East longitude (deg) + + .. note:: + + The Matlab wrapper handles calculation of runtype strlenIn, + OutfileByte, strlenOut. OutfileByte and strlenOut will be set + appropriately for a temporary file (`onera_desp_lib_sgp4_tle.tmp` or + `onera_desp_lib_sgp4_tle.tmp.####`). The wrapper reads the library + routine's output from the temporary file and passes it back as a + Matlab structure. The temporary file is deleted, so the Matlab + structure is the only result of a successful call to sgp4_tle. In + order to avoid a memory overflow for very long TLE runs, it is + possible to leave the output in a text file (as in the FORTRAN call): + the syntax is then :code:`onera_desp_lib_sgp4_tle(InFile,OutFile)` + + :callseq MATLAB: pos = onera_desp_lib_sgp4_tle(InFileByte) %implies runtype=0 + pos = onera_desp_lib_sgp4_tle(startsfe,stopsfe,deltasec,InFileByte) %implies runtype=1 + :callseq IDL: result = call_external(lib_name, 'sgp4_tle_', runtype,startsfe,stopsfe,deltasec,InFileByte,strlenIn,OutFileByte,strlenOut, /f_value) + :callseq FORTRAN: CALL sgp4_tle1(runtype,startsfe,stopsfe,deltasec,InFileByte,strlenIn,OutFileByte,strlenOut) + +.. irbem:routine:: SGP4_ELE + + Compute orbit coordinates from orbital elements. + + SGP4 stands for Simplified General Perturbation -4 and consists in an orbit + propagator. This function allows one to produce orbit coordinates from + different types of orbital elements. More about SGP4 can be found at: + http://celestrak.com/NORAD/documentation/spacetrk.pdf . + + For those who are familiar with SGP4 code, be aware for one difference + between orginal SGP4 code and the one provided here: input start and stop + time and time step are not in minutes but in seconds. This was chosen for + convenience. + + :param integer sysaxesOUT: key for the output coordinate system (see :ref:`sysaxes`) + :param integer year: year of start date + :param integer month: month of start date + :param integer day: day of start date + :param integer hour: hour of start time + :param integer minute: minute of start time + :param integer seconds: seconds of start time + :param double e1-e6: orbital elements - see definition according to `options` array + :param array of 5 integer options: type of orbital elements: + + - `options(1) = 1` : ONERA-type elements: + + * `e1` : inclination (deg) + * `e2` : geocentric altitude of perigee (km) + * `e3` : geocentric altitude of apogee (km) + * `e4` : longitude of the ascending node (deg) + * `e5` : + + - `options(2) = 1` : argument of perigee (deg) + - `options(2) = 2` : longitude of perigee (deg) + + * `e6` : + + - `options(3) = 1` : time since perigee passage (s) + - `options(3) = 2` : true anomaly at epoch (deg) + - `options(3) = 3` : argument of latitude at epoch (deg) + - `options(3) = 4` : true longitude at epoch (deg) + - `options(3) = 5` : mean anomaly at epoch (deg) + + - `options(1) = 2` : classical type elements: + + * `e1` : semimajor axis (Re) + * `e2` : eccentricity + * `e3` : inclination (deg) + * `e4` : longitude of the ascending node (deg) + * `e5` : + + - `options(2) = 1` : argument of perigee (deg) + - `options(2) = 2` : longitude of perigee (deg) + + * `e6` : + + - `options(3) = 1` : time since perigee passage (s) + - `options(3) = 2` : true anomaly at epoch (deg) + - `options(3) = 3` : argument of latitude at epoch (deg) + - `options(3) = 4` : true longitude at epoch (deg) + - `options(3) = 5` : mean anomaly at epoch (deg) + + - `options(1) = 3` : RV-type elements: + + * `e1` : xGEI (km) + * `e2` : yGEI (km) + * `e3` : zGEI (km) + * `e4` : VxGEI (km/s) + * `e5` : VyGEI (km/s) + * `e6` : VzGEI (km/s) + + - `options(1) = 4` : SOLAR type elements: + + * `e1` : inclination (deg) + * `e2` : geocentric altitude of perigee (km) + * `e3` : geocentric altitude of apogee (km) + * `e4` : local time of apogee (hours) + * `e5` : local time of maximum inclination (hours) + * `e6` : + + - `options(3) = 1` : time since perigee passage (s) + - `options(3) = 2` : true anomaly at epoch (deg) + - `options(3) = 3` : argument of latitude at epoch (deg) + - `options(3) = 4` : true longitude at epoch (deg) + - `options(3) = 5` : mean anomaly at epoch (deg) + + - `options(1) = 5` : MEAN type elements: + + * `e1` : mean motion (rev/day) + * `e2` : eccentricity + * `e3` : inclination (deg) + * `e4` : longitude of the ascending node (deg) + * `e5` : + + - `options(2) = 1` : argument of perigee (deg) + - `options(2) = 2` : longitude of perigee (deg) + + * `e6` : + + - `options(3) = 1` : time since perigee passage (s) + - `options(3) = 2` : true anomaly at epoch (deg) + - `options(3) = 3` : argument of latitude at epoch (deg) + - `options(3) = 4` : true longitude at epoch (deg) + - `options(3) = 5` : mean anomaly at epoch (deg) + + :param double startsfe: start time from provided date (s) - can be negative + :param double stopsfe: stop time from provided date (s) - can be negative + :param double deltasec: propagation step time (s) + :output array of `NTIME_MAX` integer OUTyear: year for each orbital locations + :output array of `NTIME_MAX` integer OUTdoy: day of year for each orbital locations + :output array of `NTIME_MAX` double UT: time of day for each orbital locations (s) + :output array of `NTIME_MAX` double X1: first coordinate of orbit according to `sysaxesOUT` + :output array of `NTIME_MAX` double X2: second coordinate of orbit according to `sysaxesOUT` + :output array of `NTIME_MAX` double X3: third coordinate of orbit according to `sysaxesOUT` + :callseq MATLAB: pos = onera_desp_lib_sgp4_ele([e1,e2,e3,e4,e5,e6],startdate,enddate,deltasec,sysaxesOUT) + :callseq IDL: result = call_external(lib_name, 'sgp4_ele_', sysaxesOUT,year,month,day,hour,minute,sec, e1,e2,e3,e4,e5,e6,options,startsfe,stopsfe,deltasec,OUTyear,OUTdoy,UT,X1,X2,X3, /f_value) + :callseq FORTRAN: CALL sgp4_ele1(sysaxesOUT,year,month,day,hour,minute,sec, e1,e2,e3,e4,e5,e6,options,startsfe,stopsfe,deltasec,OUTyear,OUTdoy,UT,X1,X2,X3) + +.. irbem:routine:: RV2COE + + This function finds the classical orbital elements given the Geocentric + Equatorial Position and Velocity vectors. It comes from SGP4 distribution. + + :param array of 3 double R: position in :ref:`GEI ` (km) + :param array of 3 double V: velocity in :ref:`GEI ` (km/s) + :output double P: semilatus rectum (km) + :output double A: semimajor axis (km) + :output double ecc: eccentricity + :output double incl: inclination (rad) + :output double omega: longitude of ascending node (rad) + :output double argp: argument of perigee (rad) + :output double nu: true anomaly (rad) + :output double M: mean anomaly (rad) + :output double argLat: argument of latitude (rad) + :output double lamTrue: true longitude (rad) + :output double lonPer: longitude of periapsis (rad) + :callseq MATLAB: elements=onera_desp_lib_rv2coe(R,V) + :callseq IDL: result = call_external(lib_name, 'rv2coe_idl_', R,V,P,A,Ecc,Incl,Omega,Argp,Nu,M,ArgLat,LamTrue,LonPer, /f_value) + :callseq FORTRAN: CALL rv2coe(R,V,P,A,Ecc,Incl,Omega,Argp,Nu,M,ArgLat,LamTrue,LonPer) + diff --git a/docs/source/api/radiation_models.rst b/docs/source/api/radiation_models.rst new file mode 100644 index 00000000..2c47a4cc --- /dev/null +++ b/docs/source/api/radiation_models.rst @@ -0,0 +1,428 @@ +Radiation belt and effect models +================================ + +AE8 and AP8 models +------------------ + +.. irbem:routine:: FLY_IN_NASA_AEAP + + This function allows one to fly any spacecraft in NASA AE8 min/max and AP8 min/max models. + The output can be differential flux or flux within an energy range or integral + flux. + + .. note:: + + This routine can also provide the ESA interpolation scheme as detailed + in (`Daly et al., 1996`_) for enhanced flux interpolations at low altitudes. + This interpolation scheme can be activated using negative values for the + `whichm` parameter. + + + :param integer ntime: number of time points up to :code:`NTIME_MAX` (see :ref:`NTIME_MAX`) + :param integer sysaxes: key for the input coordinate system (see :ref:`sysaxes`) + :param integer whichm: key to select the NASA model: + + * 1 : AE8 MIN + * 2 : AE8 MAX + * 3 : AP8 MIN + * 4 : AP8 MAX + * -1 : AE8 MIN - ESA Interpolation + * -2 : AE8 MAX - ESA Interpolation + * -3 : AP8 MIN - ESA Interpolation + * -4 : AP8 MAX - ESA Interpolation + + :param integer whatf: key to select the type of flux to compute: + + * 1 : differential flux at energy E1 (MeV\ :sup:`-1` cm\ :sup:`-2` s\ :sup:`-1`) + * 2 : flux within the E1 to E2 energy range (MeV\ :sup:`-1` cm\ :sup:`-2` s\ :sup:`-1`) + * 3 : integral flux above E1 (cm\ :sup:`-2` s\ :sup:`-1`) + + :param integer Nene: number of energies + :param array of [2, `Nene`] double energy: energy levels (E1, E2), if `whatf` is 1 or 3, E2 is not considered (MeV) + :param array of `ntime` integer iyear: the year + :param array of `ntime` integer idoy: the day of year (January 1st is `idoy=1`) + :param array of `ntime` double UT: the time in seconds + :param array of `ntime` double x1: first coordinate according to `sysaxes` + :param array of `ntime` double x2: second coordinate according to `sysaxes` + :param array of `ntime` double x3: third coordinate according to `sysaxes` + :output array of [`NTIME_MAX`, `Nene`] double flux: flux values for all times and energies + :callseq MATLAB: Flux = onera_desp_lib_fly_in_nasa_aeap(sysaxes,whichm,energy,matlabd,x1,x2,x3) + :callseq IDL: result = call_external(lib_name, 'fly_in_nasa_aeap_', ntime,sysaxes,whichm,whatf,Nene,energy,iyear,idoy, UT,x1,x2,x3,flux, /f_value) + :callseq FORTRAN: CALL fly_in_nasa_aeap1(ntime,sysaxes,whichm,whatf,Nene,energy,iyear,idoy, UT,x1,x2,x3,flux) + + +.. irbem:routine:: GET_AE8_AP8_FLUX + + This function allows one to compute NASA AE8 min/max and AP8 min/max flux + for any B/Bo, L position. + + The output can be differential flux or flux within an energy range or integral + flux. + + .. note:: + + This routine can also provide the ESA interpolation scheme as detailed + in (`Daly et al., 1996`_) for enhanced flux interpolations at low altitudes. + This interpolation scheme can be activated using negative values for the + `whichm` parameter. + + + :param integer ntime: number of time points up to :code:`NTIME_MAX` (see :ref:`NTIME_MAX`) + :param integer whichm: key to select the NASA model: + + * 1 : AE8 MIN + * 2 : AE8 MAX + * 3 : AP8 MIN + * 4 : AP8 MAX + * -1 : AE8 MIN - ESA Interpolation + * -2 : AE8 MAX - ESA Interpolation + * -3 : AP8 MIN - ESA Interpolation + * -4 : AP8 MAX - ESA Interpolation + + :param integer whatf: key to select the type of flux to compute: + + * 1 : differential flux at energy E1 (MeV\ :sup:`-1` cm\ :sup:`-2` s\ :sup:`-1`) + * 2 : flux within the E1 to E2 energy range (MeV\ :sup:`-1` cm\ :sup:`-2` s\ :sup:`-1`) + * 3 : integral flux above E1 (cm\ :sup:`-2` s\ :sup:`-1`) + + :param integer Nene: number of energies + :param array of [2, `Nene`] double energy: energy levels (E1, E2), if `whatf` is 1 or 3, E2 is not considered (MeV) + :param array of `ntime` double BBo: B/Bequator for all position where to + compute the fluxes. Note that the Jensen + and Cain 1960 magnetic field model must + be used for any call to AE8min, AE8max, + AP8min and GSFC 1266 (extended to year + 1970) for any call to AP8max. + :param array of `ntime` double L: Provide McIlwain L for all position where + to compute the fluxes. Note that the + Jensen and Cain 1960 magnetic field model + must be used for any call to AE8min, + AE8max, AP8min and GSFC 1266 (extended to + year 1970) for any call to AP8max. + :output array of [`NTIME_MAX`, `Nene`] double flux: flux values for all times and energies + :callseq MATLAB: onera_desp_lib_get_ae8_ap8_flux(whichm,energy,BBo,L) + :callseq IDL: result = call_external(lib_name, 'get_ae8_ap8_flux_idl_', ntime,whichm,whatf,Nene,energy,BBo,L,,flux, /f_value) + :callseq FORTRAN: CALL get_ae8_ap8_flux (ntime,whichm,whatf,Nene,energy,BBo,L,flux ) + +.. _Daly et al., 1996: http://doi.org/10.1109/23.490889 + +AFRL CRRES models +----------------- + +.. irbem:routine:: FLY_IN_AFRL_CRRES + + This function allows one to fly any spacecraft in AFRL CRRESPRO and CRRESELE + models. The output can be differential flux or flux within an energy range + or integral flux. + + ..warning :: + + Integral flux for electron are from E to 5.75 MeV and for proton are + from E to 81.3 MeV. + + To run CRRES models you have to set the full path for the source code + directory (where CRRES data files are located). + + :param integer ntime: number of time points up to :code:`NTIME_MAX` (see :ref:`NTIME_MAX`) + :param integer sysaxes: key for the input coordinate system (see :ref:`sysaxes`) + :param integer whichm: key to select the NASA model: + + * 1 : CRRESPRO QUIET + * 2 : CRRESPRO ACTIVE + * 3 : CRRESELE AVERAGE + * 4 : CRRESELE WORST CASE + * 5 : CRRESELE Ap15 + + :param integer whatf: key to select the type of flux to compute: + + * 1 : differential flux at energy E1 (MeV\ :sup:`-1` cm\ :sup:`-2` s\ :sup:`-1`) + * 2 : flux within the E1 to E2 energy range (MeV\ :sup:`-1` cm\ :sup:`-2` s\ :sup:`-1`) + * 3 : integral flux above E1 (cm\ :sup:`-2` s\ :sup:`-1`) + + :param integer Nene: number of energies + :param array of [2, `Nene`] double energy: energy levels (E1, E2), if `whatf` is 1 or 3, E2 is not considered (MeV) + :param array of `ntime` integer iyear: the year + :param array of `ntime` integer idoy: the day of year (January 1st is `idoy=1`) + :param array of `ntime` double UT: the time in seconds + :param array of `ntime` double x1: first coordinate according to `sysaxes` + :param array of `ntime` double x2: second coordinate according to `sysaxes` + :param array of `ntime` double x3: third coordinate according to `sysaxes` + :param array of `ntime` double Ap15: preceding 15-day running average of the Ap index assuming a one day delay, ignored if `whichm` is not equal to 5 + :param byte array path: path to locate the files which describe CRRES models + :param integer path_len: length of the `path` string + :output array of [`NTIME_MAX`, `Nene`] double flux: flux values for all times and energies + :callseq MATLAB: Flux = onera_desp_lib_fly_in_afrl_crres(sysaxes,whichm,energy,matlabd,x1,x2,x3,Ap15,crres_path) + :callseq IDL: result = call_external(lib_name, 'fly_in_afrl_crres_', ntime,sysaxes,whichm,whatf,Nene,energy,iyear,idoy, UT,x1,x2,x3,Ap15,flux,path,path_len, /f_value) + :callseq FORTRAN: CALL fly_in_afrl_crres1(ntime,sysaxes,whichm,whatf,Nene,energy,iyear,idoy, UT,x1,x2,x3,Ap15,flux,path,path_len) + + +.. irbem:routine:: GET_CRRES_FLUX + + This function allows one to compute AFRL CRRESPRO and CRRESELE flux for any + B/Bo, L position. + The output can be differential flux or flux within an energy range or integral + flux. + + ..warning :: + + Integral flux for electron are from E to 5.75 MeV and for proton are + from E to 81.3 MeV. + + To run CRRES models you have to set the full path for the source code + directory (where CRRES data files are located). + + :param integer ntime: number of time points up to :code:`NTIME_MAX` (see :ref:`NTIME_MAX`) + :param integer sysaxes: key for the input coordinate system (see :ref:`sysaxes`) + :param integer whichm: key to select the NASA model: + + * 1 : CRRESPRO QUIET + * 2 : CRRESPRO ACTIVE + * 3 : CRRESELE AVERAGE + * 4 : CRRESELE WORST CASE + * 5 : CRRESELE Ap15 + + :param integer whatf: key to select the type of flux to compute: + + * 1 : differential flux at energy E1 (MeV\ :sup:`-1` cm\ :sup:`-2` s\ :sup:`-1`) + * 2 : flux within the E1 to E2 energy range (MeV\ :sup:`-1` cm\ :sup:`-2` s\ :sup:`-1`) + * 3 : integral flux above E1 (cm\ :sup:`-2` s\ :sup:`-1`) + + :param integer Nene: number of energies + :param array of [2, `Nene`] double energy: energy levels (E1, E2), if `whatf` is 1 or 3, E2 is not considered (MeV) + :param array of `ntime` double BBo: B/Bequator for all position where to + compute the fluxes. Note that the + IGRF1985 magnetic field model must be + used. + :param array of `ntime` double L: Provide McIlwain L for all position where + to compute the fluxes. Note that the + IGRF1985 magnetic field model must be + used. + :param array of `ntime` double Ap15: preceding 15-day running average of the Ap index assuming a one day delay, ignored if `whichm` is not equal to 5 + :param byte array path: path to locate the files which describe CRRES models + :param integer path_len: length of the `path` string + :output array of [`NTIME_MAX`, `Nene`] double flux: flux values for all times and energies + :callseq MATLAB: Flux = onera_desp_lib_get_crres_flux(whichm,energy,BBo,L,Ap15,crres_path) + :callseq IDL: result = call_external(lib_name, 'get_crres_flux_idl_', ntime,whichm,whatf,Nene,energy,BBo,L,Ap15,flux,path,path_len, /f_value) + :callseq FORTRAN: CALL get_crres_flux(ntime,whichm,whatf,Nene,energy,BBo,L,Ap15,flux,path,path_len) + +Other radiation models +---------------------- + +.. irbem:routine:: FLY_IN_IGE + + This function allows one to fly any geostationary spacecraft in IGE + (International Geostationary Electron) models. The use of the model is + limited to geostationary altitude as it is based on LANL-GEO bird series + (1976 to 2006) and JAXA-DRTS spacecraft (added in IGE2006). Three versions + of the model are provided: + + POLE-V1: + it covers electron energies from 30 keV-1.3 MeV (issued in 2003) + Published in Boscher D., S. Bourdarie, R. Friedel and D. Belian, A model + for the geostationary electron environment : POLE, IEEE Trans. Nuc. Sci., + 50 (6), 2278-2283, Dec. 2003. + POLE-V2: + it covers electron energies from 30 keV-5.2 MeV (issued in 2005) + Published in Sicard-Piet A., S. Bourdarie, Boscher D. and R. Friedel, A + model for the geostationary electron environment : POLE from 30 keV to 5.2 + MeV, IEEE Trans. Nuc. Sci., 53 (4), 1844-1850, Aug. 2006. + IGE-2006: + it covers electron energies from 0.9 keV-5.2 MeV (issued in 2006) + Submitted in Sicard-Piet A., S. Bourdarie, Boscher D., R. Friedel M. + Thomsen, T. Goka, H. Matsumoto, H. Koshiishi, A new international + geostationary model: IGE-2006 from 1 keV to 5.2 MeV, JGR-Space Weather, + 2007. + + POLE stands for Particle-ONERA-LANL-Electrons. The output can be + differential flux or flux within an energy range or integral flux. + + .. warning:: + + This routine returns fluxes expressed in MeV\ :sup:`-1` cm\ :sup:`-2` s\ :sup:`-1` sr\ :sup:`-1`for differential fluxes of in cm\ :sup:`-2` s\ :sup:`-1` sr\ :sup:`-1` for integral fluxes. To derive omnidirectional fluxes at GEO, one should multiply these flux values by 4π sr. + + .. warning:: + + Integral flux for electron are from E to Emax of the given + selected model. So one should be very carrefull when looking at integral + fluxes with POLE-V1 . + + :param integer launch_year: year of spacecraft start of life in space + :param integer mission_duration: duration of the mission (year) + :param integer whichm: key to select the NASA model: + + * 1 : POLE-V1 + * 2 : POLE-V2 + * 3 : IGE-2006 + + :param integer whatf: key to select the type of flux to compute: + + * 1 : differential flux at energy E1 (MeV\ :sup:`-1` cm\ :sup:`-2` s\ :sup:`-1` sr\ :sup:`-1`) + * 2 : flux within the E1 to E2 energy range (MeV\ :sup:`-1` cm\ :sup:`-2` s\ :sup:`-1` sr\ :sup:`-1`) + * 3 : integral flux above E1 (cm\ :sup:`-2` s\ :sup:`-1` sr\ :sup:`-1`) + + :param integer Nene: number of energies - if 0, then the default energies are used (their number are returned in the `Nene` parameter, and their values are returned in the `energy` parameter) in this case all arrays of size `Nene` should be at least of size 50 + :param array of [2, `Nene`] double energy: energy levels (E1, E2), if `whatf` is 1 or 3, E2 is not considered (MeV) + :output array of `Nene` double lower_flux: lower flux according to selection of whatf for all energies averaged over entire mission duration - This has to be considered as a lower envelop to bound expected flux at GEO for any solar cycle + :output array of `Nene` double mean_flux: mean flux according to selection of whatf for all energies averaged over entire mission duration - This spectrum is an averaged expected flux at GEO for any solar cycle , no margins are included at this point + :output array of `Nene` double upper_flux: upper flux according to selection of whatf for all energies averaged over entire mission duration - This has to be considered as an upper envelop for expected flux at GEO for any solar cycle, this spectrum can be used for any conservative approach as margins are included at this point. Note that the margins are energy dependant and can be assesed by looking at the ratio between `upper_flux` and `mean_flux` + :callseq MATLAB: [Lower_flux,Mean_flux,Upper_flux] = onera_desp_lib_fly_in_ige(launch_year,mission_duration,whichm,whatf,energy) + :callseq IDL: result = call_external(lib_name, 'fly_in_ige_', launch_year,mission_duration,whichm,whatf,Nene,energy,Lower_flux,Mean_flux,Upper_flux, /f_value) + :callseq FORTRAN: CALL fly_in_ige1(launch_year,mission_duration,whichm,whatf,Nene,energy,Lower_flux,Mean_flux,Upper_flux) + + +.. irbem:routine:: FLY_IN_MEO_GNSS + + This function allows one to fly any MEO GNSS type spacecraft in MEO ONERA + models. The use of the model is limited to GPS altitude (~20000 km - 55 deg + inclination) as it is based on LANL-GPS bird series (1990 to 2006). Two + versions of the model are provided: + + MEO-V1: + it covers electron energies from 280 keV-1.12 MeV (issued in 2006). Note + that in this model there is no solar cycle variations which is to say + that the model should be used for long term studies on the order of a + solar cycle duration (i.e. 11 years). + Published in Sicard-Piet A., S. Bourdarie,D. Boscher, R. Friedel and T. + Cayton, Solar cycle electron environment at GNSS like altitudes, + IAC-06-D5.2.04,2006. + MEO-V2: + known as MEO-V2, it covers electron energies from 280 keV-2.24 MeV + (issued in 2007) + + The output can be differential flux or flux within an energy range or + integral flux. + + .. warning:: + + This routine returns fluxes expressed in MeV\ :sup:`-1` cm\ :sup:`-2` s\ :sup:`-1` sr\ :sup:`-1`for differential fluxes of in cm\ :sup:`-2` s\ :sup:`-1` sr\ :sup:`-1` for integral fluxes. To derive omnidirectional fluxes, one should multiply these flux values by 4π sr. + + :param integer launch_year: year of spacecraft start of life in space + :param integer mission_duration: duration of the mission (year) + :param integer whichm: key to select the NASA model: + + * 1 : MEO-V1 + * 2 : MEO-V2 + + :param integer whatf: key to select the type of flux to compute: + + * 1 : differential flux at energy E1 (MeV\ :sup:`-1` cm\ :sup:`-2` s\ :sup:`-1` sr\ :sup:`-1`) + * 2 : flux within the E1 to E2 energy range (MeV\ :sup:`-1` cm\ :sup:`-2` s\ :sup:`-1` sr\ :sup:`-1`) + * 3 : integral flux above E1 (cm\ :sup:`-2` s\ :sup:`-1` sr\ :sup:`-1`) + + :param integer Nene: number of energies - if 0, then the default energies are used (their number are returned in the `Nene` parameter, and their values are returned in the `energy` parameter) in this case all arrays of size `Nene` should be at least of size 50 + :param array of [2, `Nene`] double energy: energy levels (E1, E2), if `whatf` is 1 or 3, E2 is not considered (MeV) + :output array of `Nene` double lower_flux: lower flux according to selection of whatf for all energies averaged over entire mission duration - This has to be considered as a lower envelop to bound expected flux at MEO-GNSS for any solar cycle + :output array of `Nene` double mean_flux: mean flux according to selection of whatf for all energies averaged over entire mission duration - This spectrum is an averaged expected flux at MEO-GNSS for any solar cycle, no margins are included at this point + :output array of `Nene` double upper_flux: upper flux according to selection of whatf for all energies averaged over entire mission duration - This has to be considered as an upper envelop for expected flux at MEO-GNSS for any solar cycle, this spectrum can be used for any conservative approach as margins are included at this point. Note that the margins are energy dependant and can be assesed by looking at the ratio between `upper_flux` and `mean_flux` + :callseq MATLAB: [Lower_flux,Mean_flux,Upper_flux] = onera_desp_lib_fly_in_meo_gnss(launch_year,mission_duration,whichm,energy) + :callseq IDL: result = call_external(lib_name, 'fly_in_meo_gnss_', launch_year,mission_duration,whichm,whatf,Nene,energy,Lower_flux,Mean_flux,Upper_flux, /f_value) + :callseq FORTRAN: CALL fly_in_meo_gnss1(launch_year,mission_duration,whichm,whatf,Nene,energy,Lower_flux,Mean_flux,Upper_flux)CALL fly_in_ige1(launch_year,mission_duration,whichm,whatf,Nene,energy,Lower_flux,Mean_flux,Upper_flux) + +Effect models +-------------- + +.. irbem:routine:: SHIELDOSE2 + + SHIELDOSE2 [Seltzer, 1994] is a computer code for space-shielding radiation + dose calculations. It determines the absorbed dose as a function of depth in + aluminium shielding material of spacecraft, given the electron and proton + fluences encountered in orbit. The code makes use of precalculated, + mono-energetic depth-dose data for an isotropic, broad-beam fluence of + radiation incident on uniform aluminium plane media. Such data are + particularly suitable for routine dose predictions in situations where the + geometrical and compositional complexities of the spacecraft are not known. + Furthermore, the restriction to these rather simple geometries has allowed + for the development of accurate electron and electron-bremsstrahlung data + sets based on detailed transport calculations rather than on more + approximate methods. + + SHIELDOSE2 calculates, for arbitrary proton and electron incident spectra, + the dose absorbed in small volumes of different detector materials for the + following aluminium shield geometries: + + * in a semi-infinite plane medium, as a function of depth; irradiation is + from one side only (the assumed infinite backing effectively insures + this). + * at the transmission surface of a plane slab, as a function of slab + thickness; irradiation is from one side only. + * at the centre of a solid sphere, as a function of sphere radius; + irradiation is from all directions. + + .. note:: + + Below is provided a reasonable thickness array in g/cm2 with IMAX=70 + + .. code-block:: FORTRAN + + data Zin /1.000E-06,2.000E-06,5.000E-06,1.000E-05,2.000E-05,5.000E-05,1.000E-04,2.000E-04,& + 5.000E-04,1.000E-03,1.000E-01,2.000E-01,5.000E-01,7.000E-01,1.000E+00,1.250E+00,& + 1.500E+00,1.750E+00,2.000E+00,2.500E+00,3.000E+00,3.500E+00,4.000E+00,4.500E+00,& + 5.000E+00,6.000E+00,7.000E+00,8.000E+00,9.000E+00,1.000E+01,1.100E+01,1.200E+01,& + 1.300E+01,1.400E+01,1.500E+01,1.600E+01,1.700E+01,1.800E+01,1.900E+01,2.000E+01,& + 2.100E+01,2.200E+01,2.300E+01,2.400E+01,2.500E+01,2.600E+01,2.700E+01,2.800E+01,& + 2.900E+01,3.000E+01,3.100E+01,3.200E+01,3.300E+01,3.400E+01,3.500E+01,3.600E+01,& + 3.700E+01,3.800E+01,3.900E+01,4.000E+01,4.100E+01,4.200E+01,4.300E+01,4.400E+01,& + 4.500E+01,4.600E+01,4.700E+01,4.800E+01,4.900E+01,5.000E+01,0.000E+00/ + + :param integer idet: detector type: + + #. Al detector + #. Graphite detector + #. Si detector + #. Air detector + #. Bone detector + #. Calcium Fluoride detector + #. Gallium Arsenide detector + #. Lithium Fluoride detector + #. Silicon Dioxide detector + #. Tissue detector + #. Water detector + + :param integer inuc: nuclear interaction to account for: + + #. No nuclear attenuation for protons in Al + #. Nuclear attenuation, local charged-secondary energy deposition + #. Nuclear attenuation, local charged-secondary energy deposition, and approx exponential distribution of neutron dose + + :param integer imax: number of shielding depth (up to 71) - it is recommended to set this number close to maximum allowed value to compute accurate doses in semi-infinite aluminium medium and at center of aluminium spheres + + :param integer iunt: key to set the shielding depth unit: + + #. Mils + #. g/cm2 + #. mm + + :param array of `imax` double Zin: thickness in unit as specified by `iunt`. + :param double EminS: min energy of solar protons spectrum (MeV) + :param double EmaxS: max energy of solar protons spectrum (MeV) + :param double EminP: min energy of trapped protons spectrum (MeV) + :param double EmaxP: max energy of trapped protons spectrum (MeV) + :param integer NPTSP: number of spectrum points which divides proton spectra for integration - a value of 1001 is recommended + :param double EminE: min energy of trapped electrons spectrum (MeV) + :param double EmaxE: max energy of trapped electrons spectrum (MeV) + :param integer NPTSE: number of spectrum points which divides electron spectra for integration - a value of 1001 is recommended + :param integer JSMAX: number of points in falling spectrum of solar protons, max allowed=301 + :param integer JPMAX: number of points in falling spectrum of trapped protons, max allowed=301 + :param integer JEMAX: number of points in falling spectrum of trapped electrons, max allowed=301 + :param double eunit: conversion factor from /energy to /MeV; e.g. eunit = 1000 if flux is /keV + :param double duratn: mission duration in multiples of unit time (s) + :param array of 301 double ESin: energy of solar proton spectrum (MeV) + :param array of 301 double SFLUXin: solar flare flux for solar protons (/energy/cm\ :sup:`2`) + :param array of 301 double EPin: energy of trapped proton spectrum (MeV) + :param array of 301 double PFLUXin: incident omnidirectional flux for trapped protons (/energy/cm\ :sup:`2`/s) + :param array of 301 double EEin: energy of trapped electron spectrum (MeV) + :param array of 301 double EFLUXin: incident omnidirectional flux for trapped electrons (/energy/cm\ :sup:`2`/s) + :output array of [71, 3] double SolDose: dose profile for solar protons (rads) + + #. Dose in semi-infinite aluminium medium + #. Dose at transmission surface of finite aluminium slab shields + #. 1/2 Dose at center of aluminium spheres + + :output array of [71, 3] double ProtDose: dose profile for trapped protons (rads) + :output array of [71, 3] double ElecDose: dose profile for trapped electrons (rads) + :output array of [71, 3] double BremDose: dose profile for Bremsstrahlung (rads) + :output array of [71, 3] double TotDose: total dose profile (rads) + :callseq MATLAB: [ProtDose,ElecDose,BremDose,SolDose,TotDose] = onera_desp_lib_shieldose2(ProtSpect,ElecSpect,SolSpect,Target,...) + :callseq IDL: result = call_external(lib_name, 'shieldose2idl_', IDET,INUC,IMAX,IUNT,Zin,EMINS,EMAXS,EMINP,EMAXP,NPTSP,EMINE,EMAXE,NPTSE,JSMAX,JPMAX,JEMAX,EUNIT,DURATN,ESin,SFLUXin,EPin,PFLUXin,EEin,EFLUXin,SolDose,ProtDose,ElecDose,BremDose,TotDose,/f_value) + :callseq FORTRAN: CALL shieldose2(IDET,INUC,IMAX,IUNT,Zin,EMINS,EMAXS,EMINP,EMAXP,NPTSP,EMINE,EMAXE,NPTSE,JSMAX,JPMAX,JEMAX,EUNIT,DURATN,ESin,SFLUXin,EPin,PFLUXin,EEin,EFLUXin,SolDose,ProtDose,ElecDose,BremDose,TotDose) + diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..1d2f802f --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,73 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys + +sys.path.append(os.path.abspath("./_ext")) + +# -- Project information ----------------------------------------------------- + +project = 'IRBEM' +copyright = '2024, PRBEM' +author = 'PRBEM' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['routine'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'pydata_sphinx_theme' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] +html_css_files = ['css/irbem.css'] +html_theme_options = { + "navigation_depth": 2, + "navbar_end": ["navbar-icon-links"], + "secondary_sidebar_items": ["page-toc"], + "external_links": [ + {"name" : "Github page", "url" : "https://github.com/PRBEM/IRBEM"}, + {"name" : "PRBEM Website", "url" : "https://prbem.github.io"}, + ], + "icon_links": [ + { + "name": "GitHub", + "url": "https://github.com/PRBEM/IRBEM", + "icon": "fa-brands fa-square-github", + "type": "fontawesome", + }, + ], + } + +html_sidebars = { + "irbem-routines" : [], +} diff --git a/docs/source/fortran.rst b/docs/source/fortran.rst new file mode 100644 index 00000000..ebc0cf44 --- /dev/null +++ b/docs/source/fortran.rst @@ -0,0 +1,12 @@ +Using with FORTRAN +------------------ + +The library is written is FORTRAN 77 so it is very easy to CALL any subroutine from any FORTRAN code. + +A call to the library is trivial. Make sure anyway that the variables are of the same type as defined in the detailled functions (subroutines). + +To link any FORTRAN source code with the static library you have to add at the end of the compilation command the option -Lpath where path allows to locate the static library file and the option -loneradesp (make sure the static lib name is liboneradesp.a) + +If you have been using the Makefile to build the library then you have to add the proper option depending on the compiler in order to force the compiler to add only a single underscore to any subroutine. e.g. with g77 the option is -fno-second-underscore. + + diff --git a/docs/source/idl.rst b/docs/source/idl.rst new file mode 100644 index 00000000..c66618bc --- /dev/null +++ b/docs/source/idl.rst @@ -0,0 +1,29 @@ +Using with IDL +-------------- + +We provide a set of IDL wrappers for the IRBEM FORTRAN library through the use of a shared library file (.dll on windows, .so on Unix). +IDL access to any FORTRAN function with the use of the IDL function :code:`CALL_EXTERNAL` (see IDL manual for more details). + +IDL installation +^^^^^^^^^^^^^^^^ + +The IRBEM compile scripts will create the shared library file for use with IDL (or Matlab) and is given a name "libirbem.dll" or "libirbem.so" depending on the platform. +The `lib_name` can be defined from IDL by the following: + +.. code-block:: + + case !version.os of + 'linux':ext='so' + 'sunos':ext='so' + 'Win32':ext='dll' + endcase + lib_name=libirbem+'.'+ext + +Thus, in order to access the library and the wrappers, the user needs only to use the :code:`CALL_EXTERNAL` function where "image" (here refers as `lib_name` in the detailled function descriptions) +provide the path+name of the shared library file. + +IDL usage +^^^^^^^^^ + +When calling from IDL using :code:`call_external`, ALL input and output variables have to be declared in the correct type. +Failure to do this will result in a very ungracefull idl exit with no error messages or possibility of tracing! In general, integers need to be declared as longs and floats as double. \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..f29801f2 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,62 @@ +IRBEM Library user manual +========================= + +The International Radiation Belt Environment Modeling (IRBEM) library is a set +of source codes dedicated to radiation belt modeling. The library facilitates +the calculation of magnetic coordinates and drift shells using various external +magnetic field models. Further routines are provided for various spatial +coordinate and time format transformations. + +The library can be called from FORTRAN or C code and from Python, IDL or MATLAB +code. For Python, IDL and MATLAB, wrappers are provided in the distribution package. +The `SpacePy python package `_ does also provide a +wrapper to the IRBEM library (`spacepy.irbempy`). + +The International Radiation Belt Environment Modeling (IRBEM) library is freely +distributed under the umbrella of `COSPAR `_'s `Panel +on Radiation Belt Modeling (PRBEM) `_. + +For any questions, suggestions or to report bugs please visit the `issue tracker +`_ at the `source repository on GitHub +`_. + +Publication aknowledgement +-------------------------- +When publishing research that used IRBEM, please provide appropriate credit to the IRBEM team via acknowledgment: + + We acknowledge the use of the IRBEM library (XXX), the latest version of which can be found at https://doi.org/10.5281/zenodo.6867552. + +where `XXX` is replaced by one of the following, depending on if you are using an official release library or a repository version of the library: + +* Official Release: `XXX = "version X.Y.Z"` where `X.Y.Z` is the version number of the official release that was used (https://github.com/PRBEM/IRBEM/releases) +* Repository Version: `XXX = "repository version YYY"` where `YYY` is the output of :code:`git rev-parse --short HEAD` + + +Library content +--------------- +.. toctree:: + :maxdepth: 2 + + user-manual + api/api + irbem-routines + + +Rule of use +----------- + +This library is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License +for more details. You should have received a copy of the GNU Lesser General +Public License along with this library. If not, see +http://www.gnu.org/licenses/. + +COSPAR does not warrant or assume any legal liability or responsibility for the +accuracy, completeness, use, or usefulness of any information, apparatus, +product, or process disclosed in documents and software available from the +IRBEM library or developed as a result of the use of information or software +made available from the library. diff --git a/docs/source/irbem-routines.rst b/docs/source/irbem-routines.rst new file mode 100644 index 00000000..9d7d98ef --- /dev/null +++ b/docs/source/irbem-routines.rst @@ -0,0 +1,3 @@ +Routine Index +============= + diff --git a/docs/source/matlab.rst b/docs/source/matlab.rst new file mode 100644 index 00000000..321d609b --- /dev/null +++ b/docs/source/matlab.rst @@ -0,0 +1,110 @@ +Using with MATLAB +----------------- + +We provide a set of Matlab wrappers for the IRBEM FORTRAN library through the use of a shared library file (.dll on windows, .so on Unix). Matlab refers to this type of interface as a "mex file". In addition to the shared library file, Matlab requires a C-style header file that includes the C-style calling syntax for each FORTRAN function. This .h file is provided with the IRBEM Matlab library. For historical reasons, the Matlab routines and files are prefixed with "onera_desp_lib" rather than "irbem". + +MATLAB installation +^^^^^^^^^^^^^^^^^^^ +.. warning:: + + These MATLAB installation instructions are outdated. + +.. todo Update the MATLAB installation instructions + +Easy way for 32-bit windows users +""""""""""""""""""""""""""""""""" + +* Manually create your top-level folder "irbem" +* Download the `matlab folder tarball`_, and untar/unzip its contents into a folder called "irbem\\matlab" +* Download the `data folder tarball`_, and untar/unzip its contents into a folder called "irbem\\data" +* Open Matlab +* Under the File menu, click "Set Path" +* Add "irbem\\matlab" to your Matlab path +* Add "irbem\\data" to your Matlab path +* Click "Save" to save your new Matlab path for future sessions +* Download the `32-bit windows DLL`_ and save it as "irbem\\matlab\\onera_desp_lib.dll" + +Sort of easy way for 64-bit windows users +""""""""""""""""""""""""""""""""""""""""" + +* Do all the steps above, except download the `64-bit windows DLL`_ and save it as "irbem\\matlab\\onera_desp_lib.dll" +* Then you have to install the latest free Microsoft Visual Studio, including its "redistributables" (these are DLLs needed by the IRBEM library and Matlab requires this compiler to acceass any DLL) +* Then you have to add the following DLLs to the matlab folder where onera_desp_lib.dll resides. (We're working on a version of the DLL that does not have these dependencies): + + - (Except where noted, these are part of cygwin64, but can sometimes be found on-line without installing it) + - libgcc_s_seh-1.dll + - libgfortran-3.dll + - libquadmath-0.dll + - (These one may not be needed anymore, or only need for extras) + - libgsl-0.dll + - libgcc_s_sjlj-1.dll + - libgslcblas-0.dll + - IEShims.dll (usually found in the internet explorer folder, e.g., c:\\program files\\internet explorer. Copy it) + +Hard way for everyone else +"""""""""""""""""""""""""" +The IRBEM make file (call make help from irbem/trunk) will create the shared library file +for use with IDL or Matlab. A copy of the shared library is created in the "matlab" +subdirectory, and is given a name "onera_desp_lib.dll" or "onera_desp_lib.so" depending on +the platform. Thus, in order to access the library and the wrappers, the user needs only add +the "matlab" subdirectory (e.g. "c:\\irbem\\matlab") to the Matlab path. In order for the +library to easily locate the data files that it needs, it is also advisable to add the "data" +subdirectory to the Matlab path. Matlab provides a GUI interface to add folders to the search +path from "Set Path" entry on the "File" menu. It is also possible to add these two folders to +the path using the Matlab "addpath" command; however, this command does not make the change +to the path permanent, so that "addpath" will have to be issued once in each new Matlab +session. The "savepath" function can make the path change permanent, as can the GUI path +manager interface. Thus, one could use the following commands, if the IRBEM library is +located in "c:\\irbem": + +.. code-block:: + + addpath c:\irbem\matlab c:\irbem\data + savepath + +.. _`matlab folder tarball`: http://sourceforge.net/p/irbem/code/HEAD/tarball?path=/trunk/matlab +.. _`data folder tarball`: http://sourceforge.net/p/irbem/code/HEAD/tarball?path=/trunk/data +.. _`32-bit windows DLL`: http://sourceforge.net/p/irbem/code/HEAD/tree/trunk/onera_desp_lib_Win32_x86.dll?format=raw +.. _`64-bit windows DLL`: http://sourceforge.net/p/irbem/code/HEAD/tree/trunk/onera_desp_lib_Win64_x86.dll?format=raw + +MATLAB usage +^^^^^^^^^^^^ + +The Matlab wrappers are built to provide Matlab-like function calls into the library. These wrappers handle loading the library into Matlab's function space, formatting inputs and outputs for proper calls to the library, and providing "vectorized" functionality wherever reasonable. Each wrapper function will determine whether the FORTRAN library has been loaded, and, if not, attempt to load it from the default location (anywhere in the Matlab path). + +Each .m file provided includes a robust set of helps obtainable via help in the usual Matlab way. This help call will provide details of how to call the function. + +Although the FORTRAN library often limits the size of arrays, the Matlab wrappers typically handle arbitrarily large array inputs by splicing together multiple calls to the library. Also, in many cases, when a set of arrays is expected as input, the Matlab wrappers will accept scalars for some, which will be repeated (via Matlab's repmat function) to be the same size as the other array arguments. + +In many cases, the library requires integer inputs that represent different options, e.g., kext=5 for the Olson-Pfitzer Quiet external field model. In most cases, the Matlab wrapper supports string (keyword) inputs in place of the integer values. This keyword approach is implemented for kext, options, sysaxes, and whichm, among others. + +Whenever date/time arguments are required by the FORTRAN library, the Matlab library expects Matlab Date Numbers (construct argument "matlabd" with Matlab's datenum function). + +The FORTRAN library function fly_in_afrl_crres requires a set of text files. If the path to these files is not specified, the wrapper will attempt to guess it by locating one of these, 'crrespro_quiet.txt' in the Matlab search path. + +When available from MATLAB a calling sequence is provided for each function (see detailled description of each functions). + +MATLAB helper functions +^^^^^^^^^^^^^^^^^^^^^^^ + +The following function creates the proper maginputs array for use with the field models: + +.. code-block:: + + maginputs = onera_desp_lib_maginputs(Kp,Dst,Nsw,Vsw,Psw,ByGSM,BzGSM,G1,G2,G3,W1,W2,W3,W4,W5,W6,AL); + +The following funnction will load the shared library file from the non-default location: + +.. code-block:: + + onera_desp_lib_load(libfile,headerfile); + +The following functions are used by the library to convert the Matlab wrapper inputs into the inputs needed by the FORTRAN library. +These include "as appropriate" the look-up tables that convert keyword inputs into the integer constants used by the FORTAN library: + +.. code-block:: + + kext = onera_desp_lib_kext(kext); + options = onera_desp_lib_options(inoptions); + sysaxes = onera_desp_lib_sysaxes(sysaxes) ; + [iyear,idoy,UT] = onera_desp_lib_matlabd2yds(matlabd); diff --git a/docs/source/python.rst b/docs/source/python.rst new file mode 100644 index 00000000..838b09d7 --- /dev/null +++ b/docs/source/python.rst @@ -0,0 +1,29 @@ +Using with Python +----------------- + +We provide a set of Python wrappers for the IRBEM Fortran library through the use of a shared library file (.so on Unix). The wrapper is found in python/IRBEM.py. Python interfaces with the compiled shared library file with ctypes. + +Python wrapper install +^^^^^^^^^^^^^^^^^^^^^^ + +Compile the Fortran source as instructed by the README.install file. This will create the shared object file, "onera_desp_lib_linux....so" in the source firectory. + +Change directory into the python folder and add the Python wrapper paths with "sudo python3 setup.py install" + +Check that the installation worked by running the provided test scripts (:code:`python/<...>test_and_visualizations.py`). + +If the wrapper crashes with the error "Either none or multiple .so files found in the sources folder!", check that the shared object exists in the source folder. + +Python usage +^^^^^^^^^^^^ + +The Python wrapper :code:`IRBEM.py`` currently consists of two classes that load the shared object file. +This class interface is used to avoid redudant user input formatting code. :code:`IRBEM.py` currently contains wrappers for the magnetic field library via the :code:`MagFields` class +and coordinate transformation library via the :code:`Coords` class. +The two classes contain methods which interface with the various IRBEM functions. +The output from each IRBEM wrapped function can be accesed with the usual return statement and :code:`_output` class attributes. + +Current wrapped magnetic field functions are :irbem:ref:`make_lstar`, :irbem:ref:`drift_shell`, :irbem:ref:`find_mirror_point`, +:irbem:ref:`find_foot_point`, :irbem:ref:`trace_field_line`, and :irbem:ref:`find_magequator`. For more documentation, call :code:`help()`. + +Example code can be found in the :code:`python/<...>test_and_visualizations.py` files. \ No newline at end of file diff --git a/docs/source/user-manual.rst b/docs/source/user-manual.rst new file mode 100644 index 00000000..a1e58561 --- /dev/null +++ b/docs/source/user-manual.rst @@ -0,0 +1,20 @@ +User manual +=========== + +Installation +------------ + +To install the library, follow the instructions provided in the `IRBEM github repository`_. + +.. _IRBEM github repository: https://github.com/PRBEM/IRBEM?tab=readme-ov-file#installation + +How to use IRBEM +---------------- + +.. toctree:: + :maxdepth: 2 + + fortran + python + idl + matlab \ No newline at end of file