Review Tudat Estimation pages
DominicDirkx opened this issue · comments
The pages here:
https://docs.tudat.space/en/latest/_src_user_guide/state_estimation.html
need to be reviewed, and input provided on:
- Whether the functionality is clearly explained, and where additional clarifications are needed
- Whether the associated pages in the API documentation (https://py.api.tudat.space/en/latest/estimation_setup.html and https://py.api.tudat.space/en/latest/estimation.html are clear), and where additional clarification is needed
- Where the interfaces could/should be improved
- Which additional functionality should be added/exposed
- Which example applications should be added to clarify the documentation
Extensive comments per section to be found in the files attached to this post - something might/will be redundant with some of the following general comments:
- personally, I am a huge fan of justified text (provided it is a well justified text, not Word-style), don't know how that would work with many code and API references in the text
- the estimation API page is just one massive chunk what could be a bit scary at first glance, maybe adapt a structure similar to the sections in the documentation
- use one overall example file (only LRO, MEX, or ...) instead of "spacecraft-hopping" per section which happens especially in the first sections
- clearly explain what the following code-snippet is going to do BEFORE the snippet, not afterwards; it happens several times that one has no clue what the snippet/function presented there actually does until reading what comes just after the code-block
- the first sentence(s) of the section just grows longer and longer and longer with every new section (after having defined ... and having done ... and ...) just remove, it should follow naturally from the order of the sections and the links at the end of the individual sections
- first discuss and explain the easy ways of setting up a pair of link ends in the 'Link Ends Setup' section (what is now shortly done right at the end, but further expand on that) before going into detail how to manually do so
- more wrapper classes; example would be to directly enable bias in observation_setup.one_way_range() by putting bias = 0.0 as standard and not having to define the bias manually as observation_setup.absolute_bias( 0.01 ), makes the code easier to read and understand OR another example light_time_correction_settings = light_time_correction_settings could become light_time_correction_settings = ['Sun', order = 1] something in that direction
- make a separate section with 'Theory' that is necessary to know how tudat internally works, but not necessary to use it (aka help lazy students or users by filtering what is crucial to know and what is nice to know, but not important to make tudat work), such as for instance the theory about Doppler types
- personally, I am not sure if the 'Observation Models' subsection 'Available model types' is more to be put in the API with less text and more a let the code explain itself attitude, if not I found the current list-layout not very clear (read: very confusing, since it is to much text and bold and etc.)
- give more examples on the 'Observation Simulation' page, that's what I want to know as (potential) user of tudat; how can I adapt the observations to my needs, what can I get out of the tool, and how complex is it to get what I want, I suppose the other sections are (more or less) standardized for other tools as well
- combine the two sections 'Estimation Settings' and 'Performing the Estimation' and re-structure in a way that theory and associated code blocks are better connected/linked with each other
- Further expand on this new (or the two old, if not combined) 'Estimation' chapter(s), maybe even more code snippets; however I fear that there is not much left code-wise to show
- introduce some sort of comprehensive 'cheat sheet' with a compact step-by-step introduction what to do in which order to perform a successful estimation (as a sort of quick catching-up and brain re-activation after some weeks/months of tudat-iary absence)
1 - Link Ends Setup.pdf
2 - Observation. Model Setup.pdf
2-1 - Observation Models.pdf
3 - Observation Simulaiton.pdf
4 - Estimation Settings.pdf
5 - Performing the Estimation.pdf
Thanks! I'll post a detailed reply on the general points by tomorrow, but I can see you've identified plenty of points to make the documentation a lot better :)
Hello guys! Here also I have a small feedback document that I made. I still have some parts of the API to be reviewed and thinking of some examples so an additional feedback on that will follow for sure.
Estimation_Page_Feedback.pdf
Thanks to both for your detailed comments! Below, I'll give my point-by-point opinion, overall I agree with most of the points, and I think @irmakcavdar can get started in making the many changes :)
personally, I am a huge fan of justified text (provided it is a well justified text, not Word-style), don't know how that would work with many code and API references in the text
I am as well, but I'm not sure if this is an option in the sphinx documentation. If it is, I'm all for it!
the estimation API page is just one massive chunk what could be a bit scary at first glance, maybe adapt a structure similar to the sections in the documentation
Agreed. The API is split along the tudatpy submodules, and I think it would be a good idea to split the current estimation_setup into more submodules (as is the case for propagation_setup and environment_setup). This is a change that would need to be done at the tudatpy level (and some change in the docstrings file organization). I would like to keep this task separate from the website update, but agree that it should be done, ideally after a couple of new example applications have been written, and some new functionality is implemented. Both points will help in identifying how best to split the existing submodule(s).
use one overall example file (only LRO, MEX, or ...) instead of "spacecraft-hopping" per section which happens especially in the first sections
Completely agreed, let's pick a nice ground station and planetary mission, and stick with it :)
clearly explain what the following code-snippet is going to do BEFORE the snippet, not afterwards; it happens several times that one has no clue what the snippet/function presented there actually does until reading what comes just after the code-block
Agreed, this would work better
the first sentence(s) of the section just grows longer and longer and longer with every new section (after having defined ... and having done ... and ...) just remove, it should follow naturally from the order of the sections and the links at the end of the individual sections
That makes sense, let's do it
first discuss and explain the easy ways of setting up a pair of link ends in the 'Link Ends Setup' section (what is now shortly done right at the end, but further expand on that) before going into detail how to manually do so
Does this refer to the "one_way_downlink_link_ends(), one_way_uplink_link_ends(), two_way_link_ends(), three_way_link_ends()" set of functions? If so, I would agree that the use of these functions should be emphasized more, with an example. I'm not convinced that we should start with this, but I see how it may be more clear. Let's briefly discuss this when we meet
more wrapper classes; example would be to directly enable bias in observation_setup.one_way_range() by putting bias = 0.0 as standard and not having to define the bias manually as observation_setup.absolute_bias( 0.01 ), makes the code easier to read and understand OR another example light_time_correction_settings = light_time_correction_settings could become light_time_correction_settings = ['Sun', order = 1] something in that direction
What do you mean with 'wrapper classes'? The problem with doing something like 'bias = 0.0' implies a certain type of bias (absolute?, relative?, constant?, arcwise?) The same goes for the light-time corrections, which could be one of various types (soon, anyway :) ). It may not be as clear, as the list of options is now in a looooong list in the API documentation, but 'bias settings' have similar interfaces as 'rotation settings' or 'gravity field settings'. I would be very hesitant in making one of the model types the 'preferred' one. But, perhaps I am missing part of the point, let's discuss
make a separate section with 'Theory' that is necessary to know how tudat internally works, but not necessary to use it (aka help lazy students or users by filtering what is crucial to know and what is nice to know, but not important to make tudat work), such as for instance the theory about Doppler types
To have a short section on which kind of models Tudat actually uses would indeed be useful. But, I don't want to make the website an astrodynamics textbook; Tudat users should be familiar with the material. But, the documentation should make clear and umambiguous which models are implemented exactly. I entirely agree that this is not the case for the current website, and there should be theory extensions. But, only those that are needed to allow users to place their existing knowlegde into context (for instance, which exact equation is used to calculate covariance, without derivation)
personally, I am not sure if the 'Observation Models' subsection 'Available model types' is more to be put in the API with less text and more a let the code explain itself attitude, if not I found the current list-layout not very clear (read: very confusing, since it is to much text and bold and etc.)
The idea behind this list was to have a brief overview of all the available models in Tudat (grouped where possible), also indicating their difference, with the API documentation having details on what exactly is implemented per model. But, if this is not a purpose that the current list serves, we should find a way to improve it. One note: the target audience for this list is people familiar with the various options they may expect, to see what Tudat is (not) capable of.
combine the two sections 'Estimation Settings' and 'Performing the Estimation' and re-structure in a way that theory and associated code blocks are better connected/linked with each other
If this would make the material more clear: by all means! The current split was chosen to put the settings separate from performing the actual simulation. But, if this leads to more confusion let's indeed modify it
Further expand on this new (or the two old, if not combined) 'Estimation' chapter(s), maybe even more code snippets; however I fear that there is not much left code-wise to show
Not yet, but there will be :) Perhaps some suggestions on post-processing steps could be included. Also, covariance propagation should be highlighted somewhere.
introduce some sort of comprehensive 'cheat sheet' with a compact step-by-step introduction what to do in which order to perform a successful estimation (as a sort of quick catching-up and brain re-activation after some weeks/months of tudat-iary absence)
This is a nice idea not only for the estimation, but also for the propagation. Entirely agreed!
@kgzenk I think most of the specific comments in the document are either relatively small, or align with one of the above. I've gone through them, and I'm glad to see so many comments (were you inspired by anything in particular ;)? ). I'll go through all the comments, and answer any remaining open questions in them and comments on any suggestions I have reservations about.
@irmakcavdar, thanks for the many suggestions as well :) Below is my (quick) reply to the points in your document:
Main page:
1.) Good idea. Also, this can be highlighted more in the first few (basic) estimation examples
2.) Sounds good
3.) That would be nice, we have some diagrams for the overall propagation as well. Those can be added here as well :)
- Agreed!
Variational equations:
1.) One of many spelling errors, I suspect
2.) This is a tricky one... The variational equations (and state transition/sensitivity matrix) are useful for various things apart from estimation (uncertainty analysis, mission design...), so I'd prefer to not keep them under estimation, as people may misinterpret the potential scope. But, I also agree that the current place may be confusing. Any 'intermediate' suggestions would be most welcome!
Estimation settings:
1.) This is a good point, and is (partially) a remnant of the older Tudat structure. The covariance is indeed part of the estimation, but is not a proper estimator by itself. What it is often used for is to simulate an estimation. The covariance, as calculated here, does an uncertainty propagation from observation errors to parameter errors (and under several assumptions provides the multivariate probability distribution from which a real estimation is but a single realization). Let's discuss how best to approach this point
2.) Work in progress :)
b) The main scope of the estimation module would be post-mission science analysis, where the batch method would (usually, in planetary missions) be the way to go. But I agree that the methodology is not applicable to all cases. This should be made clear (and updated when we have more!)
c) Agreed
- To be discussed :)
Notes: Link ends setup
-
Next time we talk, I can explain this. Probably faster than typing it here :)
-
So, this is not very clear in the documentation. The body_reference_point_link_end_id setting creates a ground station with a given name (which is the second argument). It can be any name you like, and is used for 'book-keeping purposes.
-
Good point. The two_way_link_ends = ... should be the same (or equivalent) to the previous code snippet
-
That's a very interesting idea. On some pages this may become a very long list, but starting each page with a quick mention of which blocks of functionality in the API will be discussed is a very nice idea. For the estimation, addressing Kai's point above:
the estimation API page is just one massive chunk what could be a bit scary at first glance, maybe adapt a structure similar to the sections in the documentation
would help a lot for this.
Hello everyone, I gave a quick look at the comments and the feedback from Dominic, indeed I can start with changes (from tomorrow onwards). I do have one small question: I believe I will do the edits on GitHub, is that correct? Already when I am on the website I can see "Edit on GitHub" written on top right.
Hi Irmak, the 'Edit on Github' is typically used for very minor changes. What you'll be doing doesn't fall in that category, I think :) This page gives instructions on how to locally build the tudat-space website:
https://tudat-developer.readthedocs.io/en/latest/primer/docs/sphinx.html#sphinx-documentation
make sure to put the tudat-space repository on the develop branch (which corresponds to the 'latest' version).
Today, someone else got this error:
Extension error:
Could not import extension sphinxcontrib.contentui (exception: No module named 'sphinxcontrib.contentui')
when first building. Use the following command in the terminal (after activating the tudat-docs environment) to fix it:
pip install sphinxcontrib-contentui
Once you're done with your changes (or part of them, that you'd like someone to review), put them on a different branch, and push them to the tudat-space repo. To merge your changes into the tudat-space develop branch, you can make a pull request.
If any of the above steps are unclear, feel free to post on Slack for some help. I realize it's a lot of new stuff :)