Convert magnetic vector to inclination and declination

[aguspesce]

Create functions to convert the three components of magnetic vectors to the intensity, inclination a declination, and vice-versa. Add new functions to the API reference and add tests for them.

[santisoler]

Looks awesome! Just some minor suggestions for the docstring. Also, should we make a note somewhere, that our coordinate is upward up, so we have a negative magnetic vector (magnetic_u) with downward magnetization? Sometimes the upward is down, which might be a little confusing for people, haha.

Thanks for the review @LL-Geo! You're right that we should probably be more explicit about directions. For Harmonica I'm considering that both for the magnetic and magnetization vectors, the vertical component points upwards. That's why we are using magnetic_u and not magnetic_z.

Sometimes the upward is down, which might be a little confusing for people, haha.

Sounds like an Escher's painting haha. Sometimes people have coordinate systems with vertical pointing down. We try to overcome that confusion by explicitly putting the word upward.

The tricky thing in these functions is that the inclination angle is defined as positive when the vector points downwards. So, the equations for transforming them are not exactly the ones in Blakely (1995): in there they use z->down.

[LL-Geo]

Sounds like an Escher's painting haha. Sometimes people have coordinate systems with vertical pointing down. We try to overcome that confusion by explicitly putting the word upward.

The tricky thing in these functions is that the inclination angle is defined as positive when the vector points downwards. So, the equations for transforming them are not exactly the ones in Blakely (1995): in there they use z->down.

I like that painting! hahaha. That's the world in my dream🤣

Yeh... 'Traditional' coordinates usually point vertically down. And always confuse people. One day I suddenly realised that the positive density generates negative gravity in SimPEG due to the definition of "positive up and down". hahaha...

[santisoler]

Sounds like an Escher's painting haha. Sometimes people have coordinate systems with vertical pointing down. We try to overcome that confusion by explicitly putting the word upward. The tricky thing in these functions is that the inclination angle is defined as positive when the vector points downwards. So, the equations for transforming them are not exactly the ones in Blakely (1995): in there they use z->down.

I like that painting! hahaha. That's the world in my dreamrofl

Yeh... 'Traditional' coordinates usually point vertically down. And always confuse people. One day I suddenly realised that the positive density generates negative gravity in SimPEG due to the definition of "positive up and down". hahaha...

Indeed! That's why we compute the g_z in Harmonica, but explicitly saying that it's the downward component, although our coordinate system has the vertical pointing upwards.

[santisoler]

@aguspesce I think this is ready to be merged after I took the liberty to make a few changes. Would you like to review it and share your thoughts?

Although it would be nice to have some example for these two functions, I think we can avoid including them here and just use these functions in other example that forward models some magnetic field. For example, the ones in #369

Thanks a lot for the time you put into this!

[aguspesce]

@santisoler and @LL-Geo thanks you for your collaboration on this and finished this code for me.