Feature request: expose time conversions
gaffarelj opened this issue · comments
A new utility should be added to allow to convert a float or an array of Julian Dates used by Tudat (seconds since J2000), to "normal" Roman dates.
To do this, the time conversions included in tudat have to be exposed. These can be seen here.
Exposing this module is done, the documentation is now in the making.
The tudatpy.astro.time_conversion module has been pushed in commit 6207a14.
The documentation is now complete too.
The new module is tudatpy.astro.time_conversion, and its associated documentation can be found here.
@FilippoOggionni and @DominicDirkx, could you give the documentation page a quick look, and confirm that there are no issues when using this new module? If so, I will then close this issue.
Great job on this @gaffarelj !
I quickly skimmed through the documentation and everything seems in order. I see that you have not built the conda package yet, correct?
A few remarks from my side:
- since this module relies a lot on time systems and references, it would be nice to have a reference (I think one for the entire page will suffice, it is not needed to add a reference for each entry) - maybe @DominicDirkx can provide a good one?
- since most (if not all) the functions are conversions, in the code snippets it would be nice to have the result of each conversion printed and actually included in the example code. I will do this, so I can also test the module in parallel
- for the reference dates (e.g., 1st January 2000 in Julian days), it would be nice to add this number (and similar ones) to tudat constants, if it is not there yet
Indeed, I haven't built the conda package. I actually haven't looked in how to do that yet.
About your remarks:
- This reference seems to be very complete, based on the International Astronomical Union resolutions from 1976, and is actually referred to by different softwares.
- Thanks for planning on improving the code snippets this way.
- Most (if not all) of the time constants refered to are taken from the physical constants already implemented in tudat. I don't think these constants are described anywhere in the API docs. Should I open an issue about this?
- Conda package: it is actually quite easy, you just need to change the git hash in this line and push the changes, the package will be built automatically on conda servers. However, if you can put it on hold for now, this might be the first release of tudatpy with a new version number 😄 can you please open a thread on Slack about starting using the correct versioning system and tag Dominic?
- Reference: awesome, I will include that.
- Constants: I meant that in the
time_conversionmodule's functions, for instance, you could replace the number 2451545.0 (J2000 in Julian days) by thetudatpy.kernel.constants.JULIAN_DAY_ON_J2000. It seems that most of the hard-coded numbers you used in the functions as default inputs are already tudat constants, let's use those, I think it is more consistent. As a side comment, you are right, there are no API docs for thetudatpy.kernel.constantsmodule, so I opened an issue (tudat-team/tudat-multidoc#21)
About the constants:
These are actually defined in timeConversions.h, and these are the ones set as default inputs (and not hard-coded numbers), see here for instance.
I then plan on exposing both the JULIAN_DAY_ON_J2000 and JULIAN_DAY_AT_0_MJD variables as enums in the time_conversion API docs.
These are actually defined in timeConversions.h, and these are the ones set as default inputs (and not hard-coded numbers), see here for instance.
I see, but I originally meant in the docstrings, where they are hard-coded (see for instance here). There, I would rather have something like:
- name: epoch_since_julian_day_zero
type: float, default = constants.JULIAN_DAY_ON_J2000
instead of the actual number (the actual number can be made explicit in the description of the function, if needed).
I then plan on exposing both the JULIAN_DAY_ON_J2000 and JULIAN_DAY_AT_0_MJD variables as enums in the time_conversion API docs.
Regarding this, I don't see the reason to expose again those variables in an enum, as they are already exposed in the tudatpy.constants module (see the exposition file here).
I made my changes in tudat-team/tudat-multidoc@6edd2f6. I am testing locally and then push it online.
@gaffarelj I saw that the last few functions do not have examples, is this intended?
Thanks a lot.
Yes, I decided to not put examples for the last functions, since they are in my opinion very straightforward so that the example included for the first one can simply be re-used and applied to the other functions.
I think not putting examples helps keep things cleaner, and easier to read through.
Until now, the "policy" was to provide an example for each function, even if it was straightforward, but I see your reasoning and what you say makes sense. This is something we can discuss on Friday, so that we can find a shared "guideline" (another similar case is the dependent variable module).
I have also tested all the functions with examples and they all work fine on my local build. For now I am going to close the issue and move it to the review, in case @DominicDirkx wants to have a look. Otherwise, Dominic, could you please move it to "done"? 🙂
This looks very good, the one thing I would add is a reference, as requested. For time scales, I find chapter 2 of this document:
https://www.usno.navy.mil/USNO/astronomical-applications/publications/Circular_179.pdf/view
very clear.
Concerning the versioning, it's on the agenda :)
Perfect. I will add this reference, then move it to "done".
The new reference has been added as part of commit 3841031.
I reopened this issue so I don't forget to proof-read the API documentation page one more time. Some placeholders are still on it.
Fixed with c919846.