add util to fetch new orbit data elemets from JPL for ssystem_major, refs #4894 (#4908)

Author: schenlap

data/ssystem_major.ini

@@ -106,14 +106,14 @@ absolute_magnitude=12.2
 albedo=0.04
 color=1., 0.9, 0.75
 name=Ananke
-orbit_AscendingNode=44.39093600694746
-orbit_Eccentricity=0.2167681894364261
-orbit_Epoch=2454619.50000
-orbit_Inclination=148.5711484137670
-orbit_LongOfPericenter=140.3109688567360000
-orbit_MeanLongitude=14.7478795145449000
-orbit_Period=648.6406641467003
-orbit_SemiMajorAxis=21600750.92227203
+orbit_AscendingNode=104.636845425029
+orbit_Eccentricity=0.1624347341275647
+orbit_Epoch=2461172.5
+orbit_Inclination=150.44203958061
+orbit_LongOfPericenter=243.558170159683
+orbit_MeanLongitude=281.155362754205
+orbit_Period=635.251164197496
+orbit_SemiMajorAxis=21302457.6999738
 parent=Jupiter
 radius=10
 rot_equator_ascending_node=213.7
@@ -236,14 +236,14 @@ color=1., 0.9, 0.75
 # source: https://arxiv.org/pdf/1803.01907.pdf
 color_index_bv=0.76
 name=Carme
-orbit_AscendingNode=157.3089190745055
-orbit_Eccentricity=0.2602970868062183
-orbit_Epoch=2454619.50000
-orbit_Inclination=168.2000198365060
-orbit_LongOfPericenter=249.8596440195790000
-orbit_MeanLongitude=168.7753954572220000
-orbit_Period=691.6548924754876
-orbit_SemiMajorAxis=22545456.68297467
+orbit_AscendingNode=238.134972157211
+orbit_Eccentricity=0.2821422476118344
+orbit_Epoch=2461172.5
+orbit_Inclination=162.576791273225
+orbit_LongOfPericenter=53.972102169784
+orbit_MeanLongitude=300.362104158294
+orbit_Period=686.257439040126
+orbit_SemiMajorAxis=22428011.7701687
 parent=Jupiter
 radius=15
 rot_equator_ascending_node=213.7
@@ -487,14 +487,14 @@ absolute_magnitude=10.0
 albedo=0.04
 color=1., 0.9, 0.75
 name=Elara
-orbit_Ascendingnode=108.1879658680286
-orbit_Eccentricity=0.1961747274882456
-orbit_Epoch=2454619.50000
-orbit_Inclination=31.98511468770062
-orbit_LongOfPericenter=271.5797601368340000
-orbit_MeanLongitude=172.2385623581720000
-orbit_Period=258.8836449322499
-orbit_SemiMajorAxis=11709431.51919092
+orbit_AscendingNode=88.7152914472438
+orbit_Eccentricity=0.2283970016050724
+orbit_Epoch=2461172.5
+orbit_Inclination=30.4070065552925
+orbit_LongOfPericenter=306.450259326176
+orbit_MeanLongitude=258.826150945454
+orbit_Period=257.465242197417
+orbit_SemiMajorAxis=11666622.2688306
 parent=Jupiter
 radius=40
 rot_equator_ascending_node=213.7
@@ -983,14 +983,14 @@ color=1., 0.9, 0.75
 # source: https://arxiv.org/pdf/1803.01907.pdf
 color_index_bv=0.69
 name=Leda
-orbit_AscendingNode=205.5729208452909
-orbit_Eccentricity=0.1849972068029340
-orbit_Epoch=2454619.50000
-orbit_Inclination=28.26096889279179
-orbit_LongOfPericenter=133.1912542293990000
-orbit_MeanLongitude=276.4502233853120000
-orbit_Period=242.2566769525344
-orbit_SemiMajorAxis=11202541.76637748
+orbit_AscendingNode=183.353312232593
+orbit_Eccentricity=0.1505902339706631
+orbit_Epoch=2461172.5
+orbit_Inclination=30.1126873203495
+orbit_LongOfPericenter=154.396551029794
+orbit_MeanLongitude=347.072484866374
+orbit_Period=240.938361260402
+orbit_SemiMajorAxis=11161863.3148253
 parent=Jupiter
 radius=5
 rot_equator_ascending_node=213.7
@@ -1010,14 +1010,14 @@ color=1., 0.9, 0.75
 # source: https://arxiv.org/pdf/1803.01907.pdf
 color_index_bv=0.72
 name=Lysithea
-orbit_AscendingNode=0.2875682490706584
-orbit_Eccentricity=0.1281232102397132
-orbit_Epoch=2454619.50000
-orbit_Inclination=24.59040357245339
-orbit_LongOfPericenter=78.9389828310578000
-orbit_MeanLongitude=337.5492383800380000
-orbit_Period=259.0469768771512
-orbit_SemiMajorAxis=11714356.05630203
+orbit_AscendingNode=333.985216226968
+orbit_Eccentricity=0.1316018764809
+orbit_Epoch=2461172.5
+orbit_Inclination=24.7730747960696
+orbit_LongOfPericenter=97.7161066412075
+orbit_MeanLongitude=79.1794111007221
+orbit_Period=258.379816351343
+orbit_SemiMajorAxis=11694234.2395946
 parent=Jupiter
 radius=12
 rot_equator_ascending_node=213.7
@@ -1268,14 +1268,14 @@ iau_moon_number=NXIII
 albedo=0.06
 color=1., 0.9, 0.75
 name=Neso
-orbit_AscendingNode=23.02370632501001
-orbit_Eccentricity=0.6299942939512408
-orbit_Epoch=2454619.50000
-orbit_Inclination=111.8841686447457
-orbit_LongOfPericenter=107.4960759
-orbit_MeanLongitude=74.4524916
-orbit_Period=9358.591084432848
-orbit_SemiMajorAxis=48373926.07254116
+orbit_AscendingNode=39.9455813464827
+orbit_Eccentricity=0.7252258986297754
+orbit_Epoch=2461172.5
+orbit_Inclination=116.440962661999
+orbit_LongOfPericenter=136.810916424016
+orbit_MeanLongitude=328.160131962877
+orbit_Period=9722.55212952078
+orbit_SemiMajorAxis=49620118.1353897
 parent=Neptune
 radius=60
 rot_equator_ascending_node=213.7
@@ -1431,14 +1431,14 @@ absolute_magnitude=10.33
 albedo=0.04
 color=1., 0.9, 0.75
 name=Pasiphae
-orbit_AscendingNode=345.6392561172470
-orbit_Eccentricity=0.2932152942598935
-orbit_Epoch=2454619.50000
-orbit_Inclination=142.0571683364765
-orbit_LongOfPericenter=185.9358722739560000
-orbit_MeanLongitude=155.7385593991940000
-orbit_Period=709.0532625178348
-orbit_SemiMajorAxis=22921971.82698924
+orbit_AscendingNode=75.0892735463153
+orbit_Eccentricity=0.4080362053444755
+orbit_Epoch=2461172.5
+orbit_Inclination=154.372463471177
+orbit_LongOfPericenter=343.958559279333
+orbit_MeanLongitude=261.997808682125
+orbit_Period=779.532806335631
+orbit_SemiMajorAxis=24416814.0924104
 parent=Jupiter
 radius=18
 rot_equator_ascending_node=213.7
@@ -1486,14 +1486,14 @@ color=1., 0.9, 0.75
 color_index_bv=0.58
 name=Phoebe
 # Osculating orbital elements from Horizons
-orbit_AscendingNode=5.471174052957098E+01
-orbit_Eccentricity=1.504428756770607E-01
-orbit_Epoch=2457939.5
-orbit_Inclination=1.522360480930054E+02
-orbit_LongOfPericenter=340.857346218
-orbit_MeanLongitude=249.190845435
-orbit_Period=5.472983303386385E+02
-orbit_SemiMajorAxis=1.290340171828820E+07
+orbit_AscendingNode=55.3384193424451
+orbit_Eccentricity=0.1771141903802747
+orbit_Epoch=2461172.5
+orbit_Inclination=152.538033465177
+orbit_LongOfPericenter=337.616767756425
+orbit_MeanLongitude=206.818716734368
+orbit_Period=549.475194535135
+orbit_SemiMajorAxis=12937594.3623976
 parent=Saturn
 radius=106.5
 rot_equator_ascending_node=0
@@ -1598,14 +1598,14 @@ iau_moon_number=NX
 albedo=0.06
 color=1., 0.9, 0.75
 name=Psamathe
-orbit_AscendingNode=312.6542992791928
-orbit_Eccentricity=0.2226171984343604
-orbit_Epoch=2454619.50000
-orbit_Inclination=119.8213439712103
-orbit_LongOfPericenter=122.424815
-orbit_MeanLongitude=45.2205867
-orbit_Period=9130.624091904599
-orbit_SemiMajorAxis=47585137.76667986
+orbit_AscendingNode=313.212243486427
+orbit_Eccentricity=0.1729056858523589
+orbit_Epoch=2461172.5
+orbit_Inclination=117.298311935016
+orbit_LongOfPericenter=129.308745302416
+orbit_MeanLongitude=306.354354984734
+orbit_Period=9487.57921657462
+orbit_SemiMajorAxis=48817389.3269963
 parent=Neptune
 radius=40
 rot_equator_ascending_node=213.7
@@ -1733,14 +1733,14 @@ color=1., 0.9, 0.75
 # source: https://arxiv.org/pdf/1803.01907.pdf
 color_index_bv=0.77
 name=Sinope
-orbit_AscendingNode=337.3608948461959
-orbit_Eccentricity=0.1823445283881716
-orbit_Epoch=2454619.50000
-orbit_Inclination=153.0924984377859
-orbit_LongOfPericenter=334.0923761708530000
-orbit_MeanLongitude=187.6932736301600000
-orbit_Period=778.6442493765837
-orbit_SemiMajorAxis=24398256.25007371
+orbit_AscendingNode=45.8202859933618
+orbit_Eccentricity=0.2831132988165712
+orbit_Epoch=2461172.5
+orbit_Inclination=157.901094053687
+orbit_LongOfPericenter=111.502754296059
+orbit_MeanLongitude=183.598166979196
+orbit_Period=722.514661081154
+orbit_SemiMajorAxis=23211177.6000168
 parent=Jupiter
 radius=14
 rot_equator_ascending_node=213.7
@@ -1881,14 +1881,14 @@ absolute_magnitude=9.0
 albedo=0.047
 color=1., 0.9, 0.75
 name=Thebe
-orbit_AscendingNode=138.9957928276344
-orbit_Eccentricity=0.01927638586266499
-orbit_Epoch=2454619.50000
-orbit_Inclination=1.088672216784552
-orbit_LongOfPericenter=210.7720658394820000
-orbit_MeanLongitude=170.4877537965110000
-orbit_Period=0.6777043648601361
-orbit_SemiMajorAxis=222412.7038632125
+orbit_AscendingNode=317.707436988255
+orbit_Eccentricity=0.01879753794359612
+orbit_Epoch=2461172.5
+orbit_Inclination=1.06731913786618
+orbit_LongOfPericenter=57.2852110786399
+orbit_MeanLongitude=108.467254294058
+orbit_Period=0.677680577823304
+orbit_SemiMajorAxis=222407.498047356
 parent=Jupiter
 radius=49.3
 rot_equator_ascending_node=213.7

guide/app_ssystem_ini.tex

@@ -722,10 +722,122 @@ \subsubsection{How to manually look up a body}
 \noindent The displayed trajectory should start at Voyager~2's encounter with Neptune on August 18, 1989 (JD 2447757.5). 
 The value of \texttt{orbit\_good=} ($2460554.5-2447757.5 = $) \texttt{12797} fulfills this idea. 
 
+\subsubsection{How to check and update moons orbital elements}
+\label{sec:ssystem.ini:MoonsOrbitalElements}
+\sectionauthor*{Stefan Schöfegger}
+
+If not handled by dedicated orbital functions, moons orbiting planets are modelled in Stellarium using Keplerian orbits. While this
+approach is computationally efficient, it does not account for gravitational perturbations
+caused by other planets and the Sun. Over longer time spans these perturbations cause the
+predicted positions to drift noticeably from the true positions, so the orbital elements
+need to be refreshed periodically.
+
+Two Python scripts are provided to support this process. Both scripts require as their first
+argument the path to \texttt{ssystem\_major.ini}.
+
+The scripts require the Python libraries \texttt{requests} and \texttt{matplotlib}, which
+can be installed via:
+\begin{commands}
+pip3 install requests matplotlib
+\end{commands}
+
+\paragraph{Comparing positions against JPL Horizons}
+
+
+\texttt{compare\_ssystem\_major\_JPL.py} queries the JPL Horizons system for reference
+positions and compares them with the positions currently computed by Stellarium. It
+produces a PDF report containing one angular-error plot per object as well as a summary
+on the last pages. In addition, a CSV-formatted summary is printed to the console.
+
+\texttt{compare\_ssystem\_major\_JPL.py} requires a running instance of Stellarium with
+the \textbf{Remote Control Plugin} enabled and active.
+
+For maximum positional accuracy when comparing, the following options can be set in
+Stellarium before running the script:
+\begin{itemize}
+  \item Geocentric coordinates: \textit{Tools:} uncheck \textit{Topocentric coordinates}
+  \item Apparent coordinates (equinox of date)
+  \item TT timescale: \textit{Time:} \textit{Time correction} $\rightarrow$ \textit{Without correction}
+\end{itemize}
+However, for the sole purpose of assessing moon orbital parameters -- for example with a
+maximum allowed error of 2\,arcmin -- these settings are not required.
+
+\begin{commands}
+python3 compare_ssystem_major_JPL.py [options] <file> [object]
+
+positional arguments:
+  file        Path to ssystem_major.ini
+  object      Optional: compare only this named object
+
+options:
+  --years     Time range in years (default: 2)
+  --step      Step size in days (default: 7)
+  --out       Output PDF filename (default: ssystem_compare.pdf)
+  --stellarium  Stellarium base URL (default: http://localhost:8090)
+  --delay     Seconds to wait after setting Stellarium time
+              (default: 0.05)
+  --max-error Warn if maximum angular error exceeds this value in
+              arcminutes
+
+# Examples:
+python3 compare_ssystem_major_JPL.py ./ssystem_major.ini
+python3 compare_ssystem_major_JPL.py ./ssystem_major.ini himalia
+python3 compare_ssystem_major_JPL.py ./ssystem_major.ini --years 1\
+  --out compare.pdf
+\end{commands}
+
+If no object name is given, all objects defined in \texttt{ssystem\_major.ini} are
+evaluated. The \texttt{--max-error} option can be used to flag objects whose maximum
+error exceeds a chosen threshold, making it easy to identify moons that require updated
+elements.
+
+\paragraph{Fetching updated orbital elements from JPL Horizons}
+
+\texttt{fetch\_ssystem\_major.py} retrieves updated orbital elements from JPL Horizons
+and prints a modified version of \texttt{ssystem\_major.ini} to the console. Only the
+orbital parameters are updated; all other entries remain unchanged. The output can be
+reviewed and then manually merged into \texttt{ssystem\_major.ini}.
+
+\begin{commands}
+python3 fetch_ssystem_major.py [options] <file> [object]
+
+positional arguments:
+  file        Path to ssystem_major.ini
+  object      Optional: update only one named object
+
+# Example:
+python3 fetch_ssystem_major.py ./ssystem_major.ini himalia
+\end{commands}
+
+Again, omitting the object name causes all objects in the file to be updated.
+
+Always review the updated elements carefully before committing them. Freshly fetched
+parameters are valid near the current epoch but may not improve long-term accuracy for
+all objects equally.
+
+Note that the newly fetched elements are fitted to the current epoch. Deviations will
+therefore still appear over time, both in the past and in the future, and will be visible
+in a subsequent comparison run. These residual errors should, however, be smaller than
+those produced by the previously stored orbital elements for current time.
+
+\paragraph{Recommended workflow}
+
+\begin{enumerate}
+  \item Run \texttt{compare\_ssystem\_major\_JPL.py} over the full object list and inspect
+        the resulting PDF to identify moons with large angular errors.
+  \item For each problematic moon, run \texttt{fetch\_ssystem\_major.py} with the object
+        name to fetch updated elements from JPL Horizons.
+  \item Run \texttt{compare\_ssystem\_major\_JPL.py} again for the same object to verify
+        that the new elements reduce the error. Comparing the before and after plots
+        provides a clear picture of the improvement.
+  \item Repeat as needed for additional objects.
+\end{enumerate}
+
+
 \subsection{Multiple Epochs for Minor Planets}
 \label{sec:ssystem.ini:MultiEpoch}
-\indexterm{asteroid!multi-epoch ephemeris}
-\indexterm{JPL Horizons!multi-epoch script}
+\indexterm[asteroid!multi-epoch ephemeris]{}
+\indexterm[JPL Horizons!multi-epoch script]{}
 
 As described in section~\ref{sec:ssystem.ini:minor}, asteroid orbital
 elements in \file{ssystem\_minor.ini} are valid only near their epoch.