Feature/environment revision

[DominicDirkx]

As requested during the Tudat meeting of Friday June 19, I'm opening a pull request of my ongoing efforts to improve the documentation on docs.tudat.space.

Pages I'm particularly keen to get input on are:

• Setting up custom models: https://github.com/tudat-team/tudat-space/blob/feature/environment_revision/docs/source/_src_user_guide/state_propagation/environment_setup/architecture/custom_settings.rst
• Interacting with the environment during propagation: https://github.com/tudat-team/tudat-space/blob/feature/environment_revision/docs/source/_src_user_guide/state_propagation/environment_setup/architecture/environment_during_propagation.rst
• Specific environment model considerations (ideas for a new name? someone had a good one during the meeting... ), second part of: https://github.com/tudat-team/tudat-space/blob/feature/environment_revision/docs/source/_src_user_guide/state_propagation/environment_setup/create_bodies/available.rst
• Overall flow of state propagation: https://github.com/tudat-team/tudat-space/blob/feature/environment_revision/docs/source/_src_user_guide/state_propagation/propagation_setup/propagation_architecture.rst
• Overview of setup of submodules (not mentioned during meeting) https://github.com/tudat-team/tudat-space/blob/feature/environment_revision/docs/source/_src_getting_started/submodules.rst
• Guide on how to modify old aerodynamic/thrust guidance code to the new setup https://github.com/tudat-team/tudat-space/blob/feature/environment_revision/docs/source/_src_user_guide/state_propagation/environment_setup/thrust_refactor/thrust_refactor.rst

However, I am interested in any input you may have!

[MiguelAvillez]

Interacting with the environment during propagation:

• Some typos: wriing, necessarilly, convert forced to accelerations, settigs, teh, atmospher, exracted
• Regarding the inertial vs gravitational mass I would add some additional comment/reference explaining the difference between the two... mostly because I don't actually know what the difference is.
• I would switch the title to "Interacting the environment during propagation" (is it too long?), as to me just "environment during propagation" isn't super instructive
• In general about the page, is the idea for it to be just a few examples of stuff that can be retrieved from the Body class?

Specific environment model considerations:

• Typos: calcualting, neede, gravitional
• "For a non-spherical central body, the current orientation of a body has an indirect influence on the altitude at which a vehicle with a given inertial state is located" - clarify that "a body" is the central body

Overview of setup of submodules:

• Typos: functitons, These objects may have various interdependencies what are difficult to manually implement, teh
• "The usability of separate functions/classes in this submodule outside of the Tudatpy framework is very limited." Is this necessary? Took me a second to realize what it refers to, and I don't think it adds much to the paragraph

Regarding these 3 pages, the level of detail seems appropriate and I think the explanations are quite clear :) I'll add some comments (if need be) about the other 2 pages later

[DominicDirkx]

Hi Miguel, thanks for the thorough read-through! I've processed each of your comments, with one exception "The usability of separate functions/classes in this submodule outside of the Tudatpy framework is very limited." This line is here to indicate that the functionality here is not made for (for instance) using only an ephemeris, only an integrator, only a gravity field, etc. outside of Tudat. The functionality generally comes as a whole (unlike things in the math or astro submodule). I've added a line to this to maybe make it more clear. What do you think?

I've also written a new page: https://github.com/tudat-team/tudat-space/blob/feature/environment_revision/docs/source/_src_user_guide/state_propagation/environment_setup/thrust_refactor/thrust_refactor.rst on how to translate old code to new code (initial post also updated). Your thoughts on that page would also be most welcome :)

[MiguelAvillez]

I've processed each of your comments, with one exception "The usability of separate functions/classes in this submodule outside of the Tudatpy framework is very limited." This line is here to indicate that the functionality here is not made for (for instance) using only an ephemeris, only an integrator, only a gravity field, etc. outside of Tudat. The functionality generally comes as a whole (unlike things in the math or astro submodule). I've added a line to this to maybe make it more clear. What do you think?

Yep, I think it's good now. Though you inserted another small typo: functionaluty

[transferorbit]

Well @DominicDirkx, I’ve managed to review precisely one of these pages so far, namely:

• Interacting with the environment during propagation I’ve included my feedback in the attached file under the # kccomment tag. code_reviewkc-_environment_during_propagation.txt

[DominicDirkx]

@transferorbit Thanks for this rigorous feedback, it's much appreciated :) Apologies for the poor spelling and sentence structure, if you see this in other files, feel free to modify and push the changes (or continue doing as you did here, whatever works) Below are a few thoughts, for us to discuss if necessary

• In principle, the user guide assumed familiarity with Python. Important question: is the terminology I am using (class, object, member, member function) also correct in Python?
• Check all the 'body' words. Do you want body, Body, or Body? That's a good question, which I was struggling with when writing. On the one hand, I would like them all to be the same, on the other hand, I think it's good that in certain cases they are links to the Body class in the API reference. Question: should they all be links to the API docs?
• Separately, there is some niggling dissonance for me about the idea of 'models' that are updated during computation. For my feeling (which may need updating, mea culpa), models (in general) are a fixed thing that a simulation is based on. Change the model, and it feels like one is by (my) definition running a different simulation. This is exactly the kind of comments I'm looking for! My way of thinking about these things is so ingrained that I probably have huge blind spots for confusions such as this one. Thanks!

[transferorbit]

• In principle, the user guide assumed familiarity with Python. Important question: is the terminology I am using (class, object, member, member function) also correct in Python?

> AFAIK these are all equivalent OOP terms in Python.

• Check all the 'body' words. Do you want body, Body, or Body? That's a good question, which I was struggling with when writing. On the one hand, I would like them all to be the same, on the other hand, I think it's good that in certain cases they are links to the Body class in the API reference. Question: should they all be links to the API docs?

> IMHO, no, they should not all be links (because, in the extreme, almost everything could end up being a link). Perhaps one per page or section is sufficient. FWIW, “body” seems like a good choice for an arbitrary (noun) physical object in the system of bodies, whereas a “Body” or Body could be a coded entity (class, object, whatever).

[gaffarelj]

(I see that all of my comments actually got sent here as well, sorry for the spam. It's probably clearer to go through them by looking at the Files changed)

[DominicDirkx]

Awesome, thanks!

[SamFayolle]

Hi Dominic, I finally had the time to go through your documentation changes. I made a few comments above (not sure that they are all relevant, feel free to disregard those that you don't like). Overall I really like it, congrats for the hard work! In particular, the propagation setup and specific considerations on environment models are great additions I think