tudat-team / tudat-multidoc Goto Github PK

Description

This issue is to clean up tudat-multidoc and properly interface it with the multidoc tool.

Checklist

• Cleanup tudat-multidoc
• Interface tudat-multidoc with the multidoc tool correctly (conda)
• Modifications to the changelog

Additional Information

• The goal is to properly interface tudat-multidoc with the multidoc tool.

Copy pasted from slack:

Also @Dominic Dirkx, @Filippo @Jonas Hener @Jeremie G, whoever is building documentation, would anyone have a moment during a docs build to use (and verify) this conda package for multidoc in place of our copy pasted source code for multidoc (for the tudatpy docs) I managed to publish the package yesterday and setup the pipeline, which will make any modifications to multidoc a lot easier to integrate now. If no one is sure what I'm referring to, then perhaps my questionable janky solution for tudatpy docs has gone under the radar luckily

I noticed that I stopped my API documentation work at the level of the estimation_setup and estimation modules.

The Estimator object, being the highest-level and arguably most important part of any tudatpy estimation task, is located a level above, which is why it slipped my attention. I'll add that to the API docs asap.

I think it'd be good for somebody to review the API docs of the estimation and estimation_setup modules (and submodules), since I have been working on them by myself and another pair of eyes never hurts.

Can be build from
tudat --> develop
tudatpy --> develop
tudat-multidoc --> main

In the process special attention could be payed to the module description, I think they could potentially be improved...
Another aspect for special attention could be if there are any un-documented members in the modules, that were added while/after I was working on it and therefore slipped through...

I suggest @DominicDirkx and @FilippoOggionni for review of the issue.

It bugs me a little that, for the API docs of enumerations, the entire text appears to be inside quotation blocks.
For instance, in the picture below, it seems to me that the text beside the green lines should be out of the lighter box, at the same "level" as the "members:" text.

I do not know if there is a reason for this or if this is caused by a mistake in how we write the docstrings.
If this is unintentional, I don't know if you @geoffreygarrett can think of a fix for this?

While autocomplete is working on different IDEs (see tudat-team/tudatpy#22), we could also think of generating our own stub files for tudatpy - we already have the content from the API reference - and disseminate them through conda.

Low priority for now but it should not be difficult to implement, as we can simply reuse the content written for the API.

See tudat-team/tudatpy#22 for more details.

The API documentation for the function environment_setup.gravity_field.spherical_harmonic includes a note referencing to another function, namely normalize_spherical_harmonic_coefficients. Such function is however nowhere in the API documentation.

The API documentation for the function runge_kutta_4 is missing. I assume it'd be something like propagation_setup.integrator.runge_kutta_4.

The compare_results function and redirect_std class that have been added to tudatpy.util have to be documented in the TudatPy API Reference.

The propagator_settings entry here:

https://tudatpy.readthedocs.io/en/latest/numerical_simulation.html#tudatpy.numerical_simulation.SingleArcSimulator

is missing.

• Writing API for MGA-DSM code
• Insert docstrings in tudatpy

Repo: https://github.com/MiguelAvillez/tudat-multidoc

@ggarrett13 I will let you elaborate more on the issue, because I am not familiar with it 🙂

• member function estimation_setup.create_parameter_set missing function argument parameter_settings

• class estimation.PodInput constructor has wrong return type and description (copy/paste error from the ConvergenceChecker)

• create_one_dimensional_vector_interpolator parameter data_to_interpolate is duplicated, placed instead of data_first_derivatives - however, part of the parameter description fits the data_first_derivatives!

• #41

• #46

• Add docstrings and API doc for environment_setup.create_simplified_system_of_bodies(). The description of this function is already given here.

• typo in estimation_setup.parameter.gravitational_parameter box on requirements (gravitu_field)

• docs missing for enums in estimation_setup.parameter module, EstimatebleParametersEnum is not unimportant so I think we should make sure this is fixed. --> found this was a matter of renaming tudatpy name EstimatebleParameterTypes to a more English EstimatableParameterTypes and fixed that right away

I was reading through some of the spice functions looking for load_standard_kernels(). I read the documentation for load_kernel(), which states that the function cleares all loaded kernels, but it should load a specific kernel, I imagine. The documentation is identical to the clear_kernels() function, where the description does fit the function name.

@jo11he you can choose which README is more suitable (lower or higher level).

Taken from issue #38 (added by @jo11he): Interpolators module could use some example snippets, else the use is not very clear, especially how to get an InterpolatorSettings object for the interpolator factory functions (here factory functions for the interpolator and the interpolator settings are on the same level, which is untypical for tudat and thus I think the snippets are necessary to clarify :) )

At the moment, explanation of the sructure of the interpolators is here:
https://tudat-space.readthedocs.io/en/latest/_src_user_guide/math/interpolators.html

Possible solutions:

• Moving this section: https://tudat-space.readthedocs.io/en/latest/_src_user_guide/math/interpolators.html#general-procedure into the API docs
• Adding a link to this tudat-space page in the module description
• Adding a link to this tudat-space page in one or more of the function docstrings

Your thoughts?

I am currently estimating space debris using optical observations (RA / Decl). Once I tried implementing a weight vector, I noticed something odd.

Say I want to estimate an orbit on 30 observations. This means I will technically have 60 observations in my observation set (30 RA, 30 Decl. observations). I accidentally used a weight vector in my estimation input that was 30 entries long, instead of 60.

This showed odd behaviour (because 60 are required in this case), LS iterations were behaving almost randomly everytime I clicked the button. But I never received an error message that my weight vector was not the right size.

It could be useful to implement a check if the weight vector is the same size as the observation set, otherwise returning an error message.

In the making of the docstrings for estimatableParameter factory functions I tried to give some info about how certain parameters depend on environment-/ acceleration-models. In some cases my knowledge was not sufficient, so I either left that out or went with some very generic formulation.

These instances are marked by a
# (%!) help!
comment in the estimation.yaml file.

I suggest @DominicDirkx to review this and add information as he sees need / fit.

This is currently available in tudat-space, but not in the API reference.

The element_conversion.spherical_to_cartesian_elementwise() function is missing from the API documentation (but is in my opinion quite a useful function).

tidal model estimatable parameters are not yet included in the API docs, mainly because I don't anything about them.

My guess is they are strongly linked to the environment_setup.gravity_field_variations module, which is not yet documented.
I recommend to document this module first, including sufficiently extensive model descriptions, then add tidal parameters in parameter module and refer to model descriptions (from either environment_setup or the parameters module directly, depending on the pathway decided on in issue #27).

I suggest @DominicDirkx to have a look at this first.

When I do a search in the search field on the live documentation page, for example for the word ”spice”, I get a list of results as shown here. Fine so far.

However, although results preview in the list of search results appears to be what I’m looking for, eg. under Creating Celestial Bodies, as shown here...

... clicking this link of the search result for Creating Celestial Bodies takes me to this page for Creating Celestial Bodies, where this entire page does not even contain the word ”spice”.

Hi,

As requested, here I write today. The issue I'm reporting only pertains to the docs and not the functioning of TudatPy itself. When implementing hybrid termination settings, I believe there should be example code or an explanation as to how one can determine on which of the termination conditions a propagation terminated (without having to inspect the state or dependent variable history). If not an explanation under the function hybrid_termination , perhaps a link to the class PropagationTerminationDetails with an explanation or example listed there.

If you have any questions please let me know.

With kind regards,

Teun

top-down:

• module
• observations_setup
• parameter_setup

As soon as there is a consensus on how and where model descriptions (mathematical, incl. clear parametrisation, as now can be found in the technical documentation pdf) will be disseminated (see this thread, there should be links to these model descriptions from the docstrings of the applicable

• environment_setup modules
• propagation_setup modules
• parameter module

Due to the use of deprecated overloads for factory functions of integrator/propagator such as:
https://py.api.tudat.space/en/latest/integrator.html#tudatpy.numerical_simulation.propagation_setup.integrator.runge_kutta_fixed_step_size
the formatting of the associated docs issue is messed up.

A partial fix was posted here:
https://tudat.slack.com/archives/C01NSEK6CLC/p1668073019477829?thread_ts=1666011882.265549&cid=C01NSEK6CLC
resulting in docstrings formatted as:

Ideally, the deprecated function should not show up in the API docs at all.

@FilippoOggionni there is a mistake (conceptual, not typo) in the documentation of the empirical acceleration (and the code example.
The acceleration is no longer "self-exerted", but registered as coming from the central body.
I don't wanna mess with your docstrings without permission, so please assign that task to me if I have the go on making the modifications.

When trying to document the current (local) version of the documentation - using either python cli d or python cli a - pydantic throws a weird error when trying to parse the initial yaml file (package.yaml) in the docstrings. I've attached the entire error output as a .txt file.
pydantic_error_output.txt

Actions:

• environment setup:
  • atmosphere (only exponential, exponential_predefined, wind, etc...)
  • aerodynamic_coefficients (only custom, tabulated, tabulated_force_only, scaled)
  • ephemeris
  • gravity field
  • radiation pressure
  • rotation model
  • shape
• propagation setup:
  • acceleration (only thrust_and_isp_from_custom_function missing)
  • dependent variables
  • integrator
  • propagator (only propagator creation - translational, rotational, etc...)
  • torque
  • thrust

Hi all,

I struggled slightly in finding the order of the estimated parameters. For my thesis, I need to estimate the periodic_spin_variations and polar_motion_amplitudes for Mars, but I did not find useful documentation for the order of these parameters. I know that periodic_spin_variations are 8 parameters and polar_motion_amplitudes are 20 parameters. But, I do need to understand the order of the periodic_spin_variations and polar_motion_amplitudes parameters for setting a specific uncertainty to each parameter. This part is missing in the documentation, and thus, I would kindly ask you whether someone can implement it. After some time, I found out that the order of the estimated parameters is located in its own class, which can be found in the include/tudat/astro/orbit_determination/estimatable_parameters directory. This was not straightforward to me, and it can be as well for other students.

Thank you in advance.

Greetings,
Carlos

The function io.read_vector_history_from_file crashes when used on Python and gives the following error:

TypeError: Unable to convert function return value to a Python type! The signature was
(vector_size: int, file_name: str) -> Dict[float, Eigen::Matrix<double,-1,1,0,-1,1>]

I've been told you are aware of this and that for some people this doesn't happen. I attach the contents of my conda environment so that hopefully the problematic module(s) can be identified.

I have not yet included the code-examples section in the estimation API docs, where we started to put code snippet examples for the usage of each documented function (see environment_setup, propagation_setup API docs for example).

@DominicDirkx you can probably assign somebody who is most suited for this task.

It seems that currently this source is used :
https://celestrak.org/SpaceData/sw19571001.txt
with some documentation here :
https://celestrak.org/SpaceData/SpaceWx-format.php

It would be nice to add this to the documentation

Title says it all:

https://tudatpy.readthedocs.io/en/latest/acceleration.html#tudatpy.numerical_simulation.propagation_setup.acceleration.relativistic_correction

To document the tudatpy.constants module, it would be great to have a constant template implemented in multidoc/template.py, and a constant parser in multidoc/parsing/api.py.

Currently, the following have to be added at the end of lines in the docstrings of tudat-multidoc:

• # [py] if the line is only for tudatpy.
• # [cpp] if the line is only for tudat.

This makes setting up examples particularly cumbersome, as these have to be added at each line of the examples in the docstrings, making their source messier (see here as an example).

@FilippoOggionni and I discussed the possibility of having a different type of keyword that could then englobe multiple lines. For instance, how about having /* [py] and [py] */ respectively open and close a set of lines that are to be parsed as if they all ended in # [py]?

add docstrings to Gravity field variations model settings

The API does not gather all the attributes/properties that a Body object shows to have when inspected in Python. In particular, the following attributes are missing from the API documentation:

ephemeris_frame_to_base_frame
flight_conditions
ground_station_list
inertia_tensor
system_models

For convenience, here's the link to the precise location where they are missing from:
https://py.api.tudat.space/en/latest/environment.html#tudatpy.numerical_simulation.environment.Body

%Add a function to calculate the tidal time lag
Q = 35600; % Jupiter quality factor from Lainey (Nature)
Qio = 50; % Io quality factor
omega = 1.76e-4; % Jupiter spin rotation in rad/s
n = 2*pi/152853.5; % Mean motion

TimeLagJup = (atan(1/Q))/(2abs(n-omega)) % on the planet
TimeLagIo = (152853.5/(2pi))*atan(1/Qio) % on the satellite

The API reference does not specify what coordinates to use for the 'initial_state' argument in the propagator settings definition. A mismatch arises if you give the ‘initial_state’ in Keplerian coordinates and the propagator is in non-Keplerian coordinates. The initial state is always to be given in Cartesian coordinates w.r.t. the central body.

A high number of exceptions are raised during the API docs build, as seen here for example (CTRL+F for the following exception was raised:).

These exceptions are raised before references are made to in-exposed differently-named attributes of tudatpy.

The user guide explicitly references the following functions, which do play an important role in the overall environment setup and which do not have an entry in the API docs yet:

environment_setup.add_aerodynamic_corefficient_interface()
environment_setup.add_raditation_pressure_interface()

These functions should be documented in https://github.com/tudat-team/tudat-multidoc/blob/main/docstrings/numerical_simulation/environment_setup/__package__.yaml

Modules that still need descriptions (the ones not mentioned are done):

• environment (to be revised, currently not very clear to me)
• propagation (to be revised, currently not very clear to me)
• math (empty)
• util (empty)
• plotting (empty)

It is not in the yaml files.

The environment_setup.ephemeris.tabulated_from_existing method should be added to the API docs.

As a followup to this issue:
tudat-team/tudat-space#99
the issues that have been identified in the API documentation should be implemented in the user guide

When going over the single arc propagation page on tudat-space I noticed that propagation_setup.propagator.translational() does not result in a valid link. I checked the API docs and saw that translational (factory function for Translational Propagator Settings) is not documented there.
@FilippoOggionni can this be fixed? Are there possibly other undocumented FFs in this module?