Documentation clarifications

[scottshambaugh]

Two points in the documentation that I was confused on that could be clarified:

• The latitude, longitude, and altitude inputs need to be relative to the WGS84 ellipsoid, rather than mean earth radius or some other coordinate system.
• The input flag time_independent is confusingly named. From my understanding, it enables latitude-dependent atmospheric structure and proper gravity variation with latitude. It does not seem to control time variations, despite its name. Took some digging in the source to figure that one out.

Also, I gotta say the library is great! Easy & intuitive to use, and really fast.

[greglucas]

The latitude, longitude, and altitude inputs need to be relative to the WGS84 ellipsoid, rather than mean earth radius or some other coordinate system.

Yes, that would be good to clarify! Everything needs to be in geodetic coordinates. There is an additional flag that would allow geopotential heights to be used, is that something you would like exposed an alternative option? Or the clarification would be enough for your use-case?

The input flag time_independent is confusingly named. From my understanding, it enables latitude-dependent atmospheric structure and proper gravity variation with latitude. It does not seem to control time variations, despite its name. Took some digging in the source to figure that one out.

This is the name "Time independent" in the Fortran source as the option for that legacy switch, so just pulled that over to the Python side.

Additional documentation PRs to clarify all of this would be more than welcome if anyone is looking to contribute!

[scottshambaugh]

There is an additional flag that would allow geopotential heights to be used, is that something you would like exposed an alternative option?

Yes please! I can work around it, but it's a convenient shorthand.

For the time_independent flag I think it's good to match the name in the fortran source, but a better description for the flag in the docs would be useful.

[cb0s]

I am not sure, if I should create a new Issue for that, but judging from the name, I think this would also fit here. Simply by reading the documentation I noticed some other shortcomings:

1. Are longitude and latitude in rad or degrees? (This only becomes apparent when going through the examples)
2. What are the default values for the inputs to the model?
3. What happens if you don't supply f10.7, or f10.7a respectively, or any other optional data for that matter? How does the performance degrade?
4. What are possible values for the flags? These are floats, could they be bools? Or are there other values than -1 and 1?
5. In which unit I am supposed to pass altitude? Orekit for instance uses [m]. From the examples I was able to conclude it's [km] for pymsis.

When I notice something else during implementation I will edit this and tell you about it. :) Btw: I really love that this package exists and I hope that you see it as constructive criticism :)

[greglucas]

@cb0s, absolutely thank you for raising these issues! Since you've figured some of them out, do you want to open a PR to fix them? Happy to have more people collaborating on improving the project.

To try and help with the f10.7 question though: When you don't specify those values we reference the observed space weather parameters file (download it if it doesn't exist). Performance is not impacted, other than a download if you don't have the file around.

[cb0s]

Hey, thanks for the quick response! I would love to contribute in the future, but I will probably not have the time to commit this in the next let's say 3 weeks. If you are fine with me adding this later, I would love to do it! :)

[greglucas]

:+1: Looking forward to your contribution when you get the time!