Added the Boberg extension for the T89c Magnetic Field Model and documentation

[lkncl]

Follow #11

Description

This PR adds a new external magnetic field model (kext=15) implementing the Boberg extension of the Tsyganenko 89c model, allowing the ring current component of T89c to be extended using Dst.

This work follows the discussion in PR #11. Instead of modifying the existing T89c implementation (kext=4), a separate model is introduced in order to preserve the original T89c behaviour.

This implementation follows the approach described by Boberg et al. https://doi.org/10.1029/95GL00948, which extends the T89 ring current coefficient C5 using a linear Dst dependence.
The model behave like T89C for $$Kp < 57$$, but it uses Dst to drive the ring current above.

Since the original relation was derived for T89a, a new fit was performed for the T89c C5 coefficient (N. Larsen, unpublished), giving the following relationship :

$$ C_5 = -13081.0 + 1034.9 * Dst $$

For practical considerations, if the provided Dst is either the OMNI* or IRBEM BADDATA value (respectively 99999 or -1e31), Dst is computed from Kp using an empirical relationship between the mean Dst value and Kp class derived from the OMNI dataset.
OMNI* https://omniweb.gsfc.nasa.gov/html/ow_data.html

$$ Dst = -\exp(1.7 + Kp / 2.5), \quad Kp \in [5,9] $$

Implementation details

• Added a separate Fortran implementation of T89BOBERG. The duplication of T89c code avoids interactions with the cached parameters (SAVE variables) used in the original implementation.
• Updated library magnetic field model documenation inside general_information.rst
• Modified the upper limit for kext
• Removed parameter caching optimization for T89 Boberg

Tests

Tests were performed to ensure consistency when switching between T89C and T89BOBERG models and to validate the Dst handling:

• Alternate calls between legacy T89 and T89BOBERG to ensure that parameters are consistent
• Tested that BADDATA calls for Dst give expected behaviour :
• Tested with a given Dst

As expected, there is no difference when Kp<57.
When Kp>=57, changin Kp does not make any difference anymore when Dst is given but it does when Dst is set to BADDATA, as expected.

[AntoineBrunet]

Thanks Lucas. It looks OK to me.
Let's invoke @drflei and @NLarsen15 to get their approval before we merge.

To celebrate the rare occurence of the addition of a new magnetic field model, I suggest incrementing the version number to 5.1.0 .

[AntoineBrunet]

We should add @NLarsen15, as he did the fits for the coeffcients.

[AntoineBrunet]

Maybe add a comment mentionning this is for T89+Boberg

[AntoineBrunet]

Maybe clearer if we say: Kp <= 5+ and Kp >= 6-

[NLarsen15]

Hi All,

Sorry for the slow reply, last week was a holiday in Japan. The implementation looks good to me, good work.
Currently there is no citation for the refit yet so one thing you could add is my email / or affiliation so that people can contact me if they have questions about the T89c Boberg.

I will let you know as soon as there is a reference for the updated Bobergs so that it can be included in the code.

• Nick

[drflei]

Hi all,
First, my apologies for the very late comments. 1) Is T89a an option in IRBEM? if yes, maybe we should include the original Boberg extension too; 2) Nick's new model based on the much larger dataset should be added, once it is published.

Fan

[lkncl]

Hi @drflei,
Thanks for sharing your comments.
Regarding 1), there is currently no implementation of T89a available in IRBEM.
Regarding 2), I completly agree with you. The addition of Nick's new model can follow the steps presented in this PR, which should facilitate the implementation once the model is published.

Best,
Lucas