[docs] basevectors_apex: return_all

[asreimer]

There appears to be old documentation in the basevectors_apex method. Specifically the return_all optional argument doesn't seem to be in the basevectors_apex method anywhere. Specifically, I think the documentation here and here should be removed.

Does that look right?

[asreimer]

Also, I think that this is confusing.

What basevectors_apex outputs are the geodetic components of the covariant and contravariant basis vectors of the QD and APEX coordinate systems at the input coordinates. The way this documentation is worded now is just a bit incomplete and initially confusing because of the lack of specificity.

I'll wait for some input before making the change.

[aburrell]

I removed the old keyword from the documentation. The second place you wanted something removed is currently accurate, so I kept it in.

Oddly enough, I found your comment more confusing than the apexpy description. I do agree that the description is terse and requires going to the paper if you are unsure about something. I think the best thing to do would be to update the description of the return values. This will let a new user better understand what, exactly, each value in the tuple is providing.

If you like, go ahead and take a stab at the docstring in basevectors_apex. Otherwise I'll try to get to it within the week.

[asreimer]

Oddly enough, I found your comment more confusing than the apexpy description.

The concepts of covariant and contravariant are inherently confusing because we are used to orthogonal coordinate systems, but what I wrote is what the algorithm outputs. e and d are covariant and contravariant basis vectors of QD in the geodectic coordinate system, so the components of the basis vectors are geodetic components (Fig 8 Laundal and Richmond 2016). Similarly, f and g covariant and contravariant basis vectors of Apex in the geodectic coordinate system. Definitely a user should read section 5 of the paper if they are confused, but the current description of the output is incomplete and arguably misleading. The basis vectors are not in QD nor Apex.

I do not agree that these lines are accurate. As far as I can tell, the function always returns a (12,N) array. See here and how the basevectors_apex function is called in other parts of the repository, such as here.

I'll try to update the docstring later on to clarify things.

[klaundal]

A quick comment: The base vectors are not the standard covariant and contravariant basis vectors, but scaled versions such that if the Earth's magnetic field was a perfect dipole, they would be orthogonal unit vectors.

I agree that the current documentation is not very clear. The base vector calculation is extremely useful when working with vector quantities, so I of course welcome any suggestion for improved documentation. If it helps, the relationship between the apex base vectors and contravariant/covariant bases is explained here: https://link.springer.com/article/10.1007/s11214-016-0275-y#Sec12 , but this is too long for a docstring I think.

[asreimer]

@klaundal Thank you for clarifying!

I'm still very confused about this, so I'm going to have to spend some time digging in before updating the docstring. Linking directly to the article will be a must for this documentation I think.

I think it would also be useful to provide a "convert_vector" function for converting vector quantities between different coordinate systems.

[klaundal]

I agree that it is confusing, which is why I struggle to come up with a brief description that can replace closer study of the paper by Richmond, or our review paper.

Regarding vector conversion, that might be a good idea, although it will again be challenging to document. For example, conversion of electric fields from geodetic to modified apex scales the magnitude depending on Earth's magnetic field, and automatically maps it to the reference height. This is very useful in statistical studies, but the behaviour might be unexpected if one is not familiar with how this works...

[aburrell]

This might be a good place to put together a little tutorial. Something that uses the base vector calculation as part of a larger physics problem. This has the advantage of not needing to be as short as a docstring and also familiarising the users with more than the most basic bits of the code.

Ashton, do you want to submit the "convert_vector" idea as an enhancement issue? I think it's a good idea.

[asreimer]

I've spent much more time going through this stuff now. In hindsight, I feel a little dumb for not getting it, but I think I understand the sources of my confusion.

This might be a good place to put together a little tutorial. -@aburrell

Yes! I'm sort of working on something right now. The magic here for me is the context in which the basis vectors are used. When you see how hard the non-orthogonal vector math can be, but how much it simplifies when using e and f or g and h, suddenly, things make a lot more sense. A docstring can't sufficiently explain this context, so a tutorial is definitely needed. Maybe a Jupyter notebook? I think there should be a Wikipedia page actually.

A quick comment: The base vectors are not the standard covariant and contravariant basis vectors, but scaled versions such that if the Earth's magnetic field was a perfect dipole, they would be orthogonal unit vectors. -@klaundal

Right! In hindsight this is rather obvious. I've studied the paper more closely and had a solid discussion with Roger Varney and Leslie Lamarche about the modified apex coordinate system, specifically the purpose of the e, f, g, and h basis vectors. I think a simple way to describe things is the following. As you'll see, it doesn't differ that much from @klaundal's comment.

General Non-Orthogonal Basis Vectors vs. Modified Apex (MA) "Scaled" Basis Vectors

The MA "basis vectors" are not actually basis vectors of the MA and Quasi Dipole (QD) coordinate systems in the standard general tensor math sense (for example, Arfken 2017). Instead, the basis vectors, e, f, g, and h, defined in Richmond 1995 and discussed in Laundal and Richmond 2016 are scaled versions, as @klaundal said. I really don't think the description of the scaling is very useful though, at least not as useful as the reason for why the vectors are scaled.

I also think it is important to be precise about our language here since "basis vector" as used in the Richmond 1995, Emmert 2010, and Laundal and Richmond 2016, doesn't mean the same thing as "basis vector" which usually refers to the formal mathematical definition. Maybe I'm just dense, but that was the first thing that confused me, so I think is is important to include in documentation.

Context

As discussed in Section 4 of Richmond 1995, the main purpose of defining the scaled basis vectors is that they make working with vector quanties much easier to work with in a non-orthogonal coordinate system. Specifically, the scaled basis vectors vector operations with electric fields and magnetic fields, and vectors that use them such as the ExB velocity and currents, much easier.

Docstring Changes

I'll make some docstring changes that summarize what I've written here. Additionally, I can work on a tutorial that can be used in conjunction with the Richmond 1995 paper, so that people like me can more easily understand the purpose of the scaled basis vectors and how to use them.

---

I think that's correct right? So, correcting my original comment, I should have said, "e and d are scalled covariant and contravariant basis vectors of QD in the geodectic coordinate system, so the components of the basis vectors are scaled geodetic components"?

[asreimer]

One last thing:

Regarding vector conversion, that might be a good idea, although it will again be challenging to document. -@klaundal

I think it could make things easier, so long as we're clear about using the scaled basis vectors. Currently, it is unclear how you map vectors from geodetic to modified apex, which is a desirable operation for things such as multi instrument comparisons during sounding rocket campaigns.

[klaundal]

@asreimer Excellent! It would be great if you make a Jupyter notebook to explain this. I can relate to your confusion, I struggled with the same things, finding the relation between textbook descriptions of tensor calculus and the Richmond basis vectors. We point to this in the introduction to Section 5 in the review paper.

Let me know if you would like me to proofread, or if I can help with something else.

If you make function(s) to convert vectors, it will be important to make clear which quantity is being converted. For example, the components of v should be calculated as v dot d_i, and E as E dot e_i. Delta B is more complicated, because it has two parts: A "FAC part", which maps along field lines, and a "horizontal current part", which doesn't. The latter, which is best described in QD coordinates, is often ignored with space based measurements, although it can be significant at low heights. My point is that the conversions require some understanding, but with the tutorial that you propose, I think it is a good idea to implement it.

[aburrell]

The only part left to do here is a tutorial.