app_ssystem_ini.tex

%% Part of Stellarium User Guide
%% Status:
%% 2016-05-16 GZ new file. This file and its handling is so complicated, it deserves proper docs.
%% 2017-06-18 GZ for v0.16.0 we have split the config file. Adapted docs.
%% TODO: document the more obscure entries. Add links to the respective chapters.

%\chapterimage{chapter-t1-bg} % Chapter heading image

\section{Solar System Configuration Files}
\label{sec:ssystem.ini}

The files\footnote{Before v0.16, there was a single file, \file{ssystem.ini}, with slightly different rules.}
 \file{ssystem\_major.ini} and  \file{ssystem\_minor.ini}  
(in the \file{data/} subdirectory of the program directory, 
contain orbital and rotational data from which Stellarium configures the Solar
System objects. 

The minor bodies can be modified by placing a privately modified 
copy of \file{ssystem\_minor.ini} into your own
\file{data/} directory (see Chapter~\ref{sec:FilesAndDirectories}). 
You can edit the file either manually or with the Solar System Editor plugin (see
Section~\ref{sec:plugins:SolarSystemEditor}). The private user file is automatically created by the Solar System Editor plugin.


%Deprecated parameters are marked by gray background. 
%Possible new parameters are marked by yellow background.
%% GZ This is no longer true. Reactivate somehow? 

Each object's data are described in its own section which is typically
named after the object name. Some section names (e.g.\ those using
diacriticals, spaces or other problematic characters) appear a bit mangled.

We list here examples for the major planets, larger moons with special
coordinate functions, minor moons with generic orbital elements, minor
planets and comets with elliptical and parabolic orbit elements.

All elements are stored in alphabetic order in the files, however it
makes more sense to present the elements in another sequence which
better reflects the meaning. The actual order of the objects in the
files, and order of entries inside an object section, is irrelevant,
but in case of duplicate entries the later entry is used.

\subsection{File ssystem\_major.ini}
\label{sec:ssystem.ini:major}


\subsubsection{Planet section}
\label{sec:ssystem.ini:Planet}

Example:
\begin{configfile}
[jupiter]
name=Jupiter
type=planet
coord_func=jupiter_special
orbit_visualization_period=4331.87

atmosphere=1
albedo=0.51
color=1., 0.983, 0.934
absolute_magnitude=-9.40

radius=71492
oblateness=0.064874
tex_map=jupiter.png #texture courtesy of Bj\xf6rn J\xf3nsson

# deprecated rotational elements
rot_equator_ascending_node=-22.203
rot_obliquity=2.222461
rot_periode=9.92491
rot_rotation_offset=-1 # use JupiterGRS patch

# WGCCRE rotational elements
rot_pole_ra=268.056595
rot_pole_ra1=-0.006499
rot_pole_de=64.495303
rot_pole_de1=0.002413
rot_pole_w0=284.95
rot_pole_w1=870.5360000

\end{configfile}


where 
\begin{description}
\item[name] English name of the planet. May appear translated. 
\item[type] Mandatory for planets: \value{planet}
\item[parent]=Sun. The body which this object is running around. Default: \texttt{Sun}
\item[coord\_func] The planet positions are all computed with a dedicated function (VSOP87 or DE43x). 
\item[orbit\_visualization\_period] number of (earth) days for how
  long the orbit should be made visible. Typically Stellarium shows
  one orbit line. The orbit slowly drifts, however.

\item[atmosphere] (0 or 1) flag to indicate whether observer locations should enable atmosphere drawing.

\item[radius] Equator radius, km.
\item[oblateness] Flattening of the polar diameter. ($1-r_{pole}/r_{eq}$)
\item[albedo] total albedo (reflectivity) of the planet. Used for ``generic''
  magnitude computation, but the major planets usually have dedicated
  magnitude formulas, so the value is not evaluated unless you are
  observing from a location outside Earth.
\item[color] Used to colorize halo. At least one of the components should be 1.
\item[tex\_map] File name of texture map in \file{textures} folder.
\item[halo] Should be true to draw a halo (simple light disk) when object too small to draw a sphere. Default: \texttt{true}
\end{description}

\paragraph{Elements for the Physical Ephemeris}

Where known, Stellarium can properly model axis rotation with the
\texttt{rot\_\ldots} entries in the element sets.  Versions prior to
0.21 had rotational elements defined with respect to the equator of
the parent object. While writing this documentation the origin and
accuracy of this model is unfortunately untraceable.  However, the IAU
Working Group on Cartographic Coordinates and Rotational Elements
(WGCCRE) and modern sources like \citet{ESAA:2013} use rotational
elements with respect to the ICRF (see section
\ref{sec:Concepts:Equatorial}). Therefore, starting with version 0.21,\newFeature{0.21}
Stellarium uses these more modern data and can now also show axes with
precessional or other motions. Data for some planet moons are
unfortunately still not available in this WGCCRE format, and therefore
the old format can still be used, but should not be used for new
entries.

\begin{description}
\item[rot\_equator\_ascending\_node] \emph{deprecated}
\item[rot\_obliquity] \emph{deprecated}
\item[rot\_rotation\_offset] \emph{deprecated} longitude of prime
  meridian. For Planets, this used to be counted from the ascending
  node of the equator over the ecliptical plane at J2000.0. For moons,
  it is the longitude of the prime meridian counted from the ascending
  node of the moon's equator over the planet equator.  A special value
  here indicates special treatment for the Great Red Spot.
\item[rot\_periode] \emph{deprecated} Duration of one sidereal rotation, in earth hours.

\item[rot\_pole\_ra]  constant of axis right ascension in ICRF, degrees
\item[rot\_pole\_ra1] change per century of axis right ascension in ICRF, degrees
\item[rot\_pole\_de] constant of axis declination in ICRF, degrees
\item[rot\_pole\_de1] change per century of axis declination in ICRF, degrees
\item[rot\_pole\_w0] longitude of the prime meridian counted from the
  ascending node of the objects's equator through the ICRF equator, degrees
\item[rot\_pole\_w1] change per day of axis rotation, degrees
\end{description}

\noindent In many cases, the attitude/rotation formulae for the North (or
``positive'') pole $(\alpha_0, \delta_0)$ are given like
\begin{eqnarray}
  \label{eq:PlanetOrientation}
  \alpha_0 &=& \mathtt{rot\_pole\_ra} + T * \mathtt{rot\_pole\_ra1}\\
  \delta_0 &=& \mathtt{rot\_pole\_de} + T * \mathtt{rot\_pole\_de1}\\
  W        &=& \mathtt{rot\_pole\_w0} + d * \mathtt{rot\_pole\_w1}
\end{eqnarray}

\noindent These cases are fully covered by the data in
\file{ssystem\_major.ini}. Corrections for solar system objects given
by \citet{ESAA:2013, WGCCRE2009, WGCCRE2009:corr, WGCCRE2015,
  WGCCRE2015:corr} have been implemented in the program.


\subsubsection{Moon section}
\label{sec:ssystem.ini:Moon}

All planet moons are defined only in \file{ssystem\_major.ini}.

Moons are special in that they orbit another planet. Therefore, the
rotational elements used to be specified relative to the equatorial
plane of the parent planet, and \texttt{orbit\_SemiMajorAxis} are
specified in kilometers.  However, \newFeature{0.21} as for the
planets (see section \ref{sec:ssystem.ini:Planet} above), current
\indexterm{IAU} reference material gives axis orientation with right
ascension and declination values for the pole in ICRF coordinates,
with some of them in motion. So again, if one of the
\texttt{rot\_pole\_...} values exist, we assume the current
standard, but keep the old elements available until we find new data.
For more complicated motion, again some special functions
are applied.

%% TODO: CHANGE THIS WHEN AXES HAVE BEEN REMADE!

\begin{configfile}
[amalthea]
name=Amalthea
type=moon
parent=Jupiter
iau_moon_number=JV

orbit_AscendingNode=141.5521520794674
orbit_Eccentricity=0.006175744402949701
orbit_Epoch=2454619.50000
orbit_Inclination=0.3864576103404582
orbit_LongOfPericenter=245.4222355150120000
orbit_MeanLongitude=224.7924893552550000
orbit_Period=0.5016370462116355
orbit_SemiMajorAxis=181994.8658358799
# orbit_visualization_period=0.5016370462116355

absolute_magnitude=7.4
albedo=0.09
color=1., 0.627, 0.492
radius=83.5
tex_map=amalthea.png
model=j5amalthea_MLfix.obj


rot_equator_ascending_node=213.7
rot_obliquity=15.5
# rot_periode=12.039289109079252
rot_rotation_offset=235.50
rot_pole_ra=268.05
rot_pole_ra1=-0.009
rot_pole_de=64.49
rot_pole_de1=0.003
rot_pole_w0=231.67
rot_pole_w1=722.6314560
\end{configfile}

where
\begin{description}
  \item[name] English name of planet moon. No number, just the name. May be translated.
  \item[type] \texttt{moon}

  \item[parent] English name of planet or parent body.
  \item[iau\_moon\_number] a short label (string) consisting of the planet's initial and the moon's Roman number in order of discovery.\newFeature{0.16.1}

  \item[coord\_func] Must be \texttt{kepler\_orbit} (default, can be left away) for moons with orbital elements given, or \texttt{<name>\_special} for 
  \item[orbit\_AscendingNode] $\Omega$
  \item[orbit\_Eccentricity] $e$
  \item[orbit\_Epoch] 
  \item[orbit\_Inclination] $i$ [degrees]
  \item[orbit\_LongOfPericenter] 
  \item[orbit\_MeanLongitude]
  \item[orbit\_Period] [days]
  \item[orbit\_SemiMajorAxis] $a$ [km]
  \item[orbit\_visualization\_period] [days] Defaults to \texttt{orbit\_Period} to show orbit as closed line. 
       This is in fact only useful in case of special functions for positioning where \texttt{orbit\_Period} is not given.

  \item[radius] Equator radius, km.
  \item[oblateness] Flattening of the polar
    diameter. ($1-r_{pole}/r_{eq}$) Bodies with non-ellipsoid shape,
    e.g. tri-axial geometry, cannot be modelled with this simple
    approach, but a 3D solid model can be shown, see below.
    
  \item[albedo] total reflectivity [0..1]
  \item[color] for drawing halo (default: 1,1,1)
  \item[halo] [=true|false] to draw a simple diffuse dot when zoomed out. Default: \texttt{true}
  \item[tex\_map] name of spherical texture map. Many moons have been mapped by visiting spacecraft! For many other moons, Stellarium applies an inverted Lunar texture image.
  \item[model] \newFeature{0.16.0}(optional) name of a 3D model for a non-spherical body in the \file{model} subdirectory of the program directory. 

  \item[rot\_equator\_ascending\_node] \emph{deprecated}
  \item[rot\_obliquity] \emph{deprecated}
  \item[rot\_rotation\_offset] \emph{deprecated} longitude of prime meridian at J2000.0. 
  \item[rot\_periode]  \emph{deprecated}  Duration of one sidereal rotation, in earth hours. For moons in bound rotation 
       (which always show one face towards their parent planet), it is best to omit this value: it defaults to \texttt{orbit\_Period * 24}. 

  \item[rot\_pole\_ra]  constant of axis right ascension in ICRF, degrees
  \item[rot\_pole\_ra1] change per century of axis right ascension in ICRF, degrees
  \item[rot\_pole\_de] constant of axis declination in ICRF, degrees
  \item[rot\_pole\_de1] change per century of axis declination in ICRF, degrees
  \item[rot\_pole\_w0] longitude of the prime meridian counted from the
    ascending node of the objects's equator through the ICRF equator, degrees
  \item[rot\_pole\_w1] change per day of axis rotation, degrees  
\end{description}



\subsubsection{Observers}
\label{sec:ssystem.ini:Observers}

Stellarium is great for excursions to the surface of any object with
known orbital elements.  Configuring a viewpoint away from a planet
requires a special kind of location.

\paragraph{Solar System Observer}
\label{sec:ssystem.ini:SolarSystemObserver}

The Solar System Observer has
been provided as a neutral view location high above the North pole of
the Solar System. It has been configured like this:
\begin{configfile}
[solar_system_observer]
name=Solar System Observer
parent=Sun
halo=false
hidden=true
coord_func=ell_orbit
orbit_Inclination=90
orbit_MeanLongitude=90
orbit_Period=70000000000
orbit_SemiMajorAxis=70000000000
rot_obliquity=90
type=observer
\end{configfile}
Note the inclination and mean longitude of 90 degrees, and that it is \texttt{hidden} and has no \texttt{halo}. 

\paragraph{Planet Observers}
\label{sec:ssystem.ini:PlanetObserver}

There are other ``observer'' locations for all planets \newFeature{0.19.2} which have moons: Earth, Mars, Jupiter, Saturn, Uranus, and Neptune.
They have all been provided as neutral view locations above the Northern hemisphere of
the respective planet. For example:
\begin{configfile}
[earth_observer]
name=Earth Observer
parent=Earth
halo=false
hidden=true
coord_func=ell_orbit
orbit_Inclination=90
orbit_MeanLongitude=90
orbit_Period=100000000000
orbit_SemiMajorAxis=149600000
rot_obliquity=90
type=observer
\end{configfile}

The distance \texttt{orbit\_semiMajorAxis} has been configured with a
distance that resembles the semimajor axis of the respective planet:
when you want to compare the views from Earth and from the observer,
light time correction should be at least approximately equal.

\subsection{File ssystem\_minor.ini}
\label{sec:ssystem.ini:minor}

Orbital elements for minor bodies are always given for a particular
\indexterm{equinox} like J2000.0 (which indicates the coordinate
reference system) and \indexterm{epoch} (date). The other planets pull
on the objects and change their orbits, most usually leading to the
objects appearing too early or too late in their orbits, but also
changing the other orbital elements. In addition, outgassing events of
comets can act like jet propulsion and change orbits in unpredictable
ways.  It is heavily recommended to update the orbital elements on a
regular basis ($2\times$/year?), or at least before you go out and are
actually observing minor bodies.  Use the Solar System Editor plugin
for this task (section~\ref{sec:plugins:SolarSystemEditor}).

You may find element sets for different equinoxes, like B1950.0. These
have to be converted to equinox J2000.0 data before being useful in
Stellarium.

\begin{description}
\item[coord\_func] is \texttt{kepler\_orbit} by
  default\newFeature{0.20}.\footnote{Previous editions used the name
    \texttt{comet\_orbit}. Now the \texttt{coord\_func} line can be
    left away, defaulting to \texttt{kepler\_orbit}.}
\item[parent] defaults to \texttt{Sun} and can be omitted.

\item[orbit\_Epoch] JDE when these elements are valid. Defaults to
  2451545.0 = the J2000.0 standard epoch.

\item[orbit\_good] can be given in days to limit computation of the
  object to the time range
  $\mathtt{epoch}\pm\mathtt{orbit\_good}$. If\newFeature{0.21.3}
  specified as \texttt{0} there is no check for out-of-range dates. If
  specified as \texttt{-1}, half the orbital period is used. The main
  purpose of this parameter is to avoid an element clash or the
  inadvertent use of outdated comet orbit elements when a periodic
  comet reappears.

\item[orbit\_ArgOfPericenter] $\omega$ [degrees]
\item[orbit\_AscendingNode] $\Omega$  [degrees]
\item[orbit\_Eccentricity] $e=0$ circular, $0<e<1$ elliptic, $e=1$ parabolic, $e>1$ hyperbolic
\item[orbit\_Inclination] $i$ [degrees] inclination against J2000 ecliptic
\item[orbit\_SemiMajorAxis] $a$ [AU]
\item[orbit\_visualization\_period] [days] %TODO does that default to sth meaningful? Do we need it at all?
\end{description}
The other parameters are like those for the major planets. 

\subsubsection{Minor Planet section}
\label{sec:ssystem.ini:MinorPlanet}

\begin{configfile}
[4vesta]
type=asteroid  
minor_planet_number=4
name=Vesta

coord_func=kepler_orbit
parent=Sun
orbit_Epoch=2457000.5
orbit_MeanAnomaly=20.86389
orbit_MeanMotion=0.27154465

orbit_ArgOfPericenter=151.19843
orbit_AscendingNode=103.85141
orbit_Eccentricity=0.0887401
orbit_Inclination=7.14043
orbit_SemiMajorAxis=2.3617933
orbit_visualization_period=1325.46

color=1., 1., 1.
halo=true
oblateness=0.0

albedo=0.423
radius=280
absolute_magnitude=3.2
slope_parameter=0.32
tex_map=vesta.png
model=4vesta_21_MLfix.obj
\end{configfile}

\begin{description}
\item[type] can be \texttt{asteroid, dwarf planet, cubewano,
  plutino, scattered disc object, Oort cloud object}. With the
exception of Pluto (which is included in \file{ssystem\_major.ini} and cannot be changed), 
all positions for minor bodies are computed with the orbiting elements given in this way. 
\end{description}

Minor planets further specify
\begin{description}
\item[orbit\_Epoch], JDE when these elements are valid.
\item[orbit\_MeanAnomaly] $M$ mean anomaly, degrees. 
\item[orbit\_MeanMotion] $n$ mean motion [degrees/day].
\end{description}

Visual magnitude is modelled from
\begin{description}
\item[absolute\_magnitude] $H$
\item[slope\_parameter] $G$.
\end{description}

Elements for rotational axis may be given just like for planets when
they are known. It is recommended to use the modern specification
(elements \texttt{rot\_pole\_...}).

\begin{description}
\item[model]
A few asteroids have been visited by spacecraft, \newFeature{0.16.0}
and for many other asteroids visual observations of stellar occultations 
by asteroids and light curve measurements have enabled researchers to derive 
3D shape models of asteroids. If a model is available in the \file{models} 
subdirectory of the program directory, this can be configured with a \texttt{model} entry.
\end{description}


\subsubsection{Comet section}
\label{sec:ssystem.ini:Comet}

Comets are tiny, and their outgassing and close approaches to the
major planets cause fast changes in their orbital elements, so that
each apparition should be specified with a dedicated section in
\file{ssystem\_minor.ini}.

Note the specification of
\begin{description}
\item[orbit\_PericenterDistance] $q$ [AU]
\item[orbit\_TimeAtPericenter] $T$  JDE of closest approach to the Sun.
\end{description}
which is more typical for comets which may have no orbital period when
they are on parabolic or hyperbolic orbits. Frequently orbital
elements are given for a date very close to perihelion so that the
perihel date can be used as default for the optional
\texttt{orbit\_Epoch}. However, this assumption does not always hold,
so we\newFeature{0.21.3} recommend to state \texttt{orbit\_Epoch} explicitly.


Comet brightness is evaluated from
\begin{equation}
  \label{eq:comet_magnitudes}
  \mathrm{mag}=\mathtt{absolute\_magnitude}+5\cdot\log{\mathrm{distance}} + 2.5\cdot\mathtt{slope\_parameter}\cdot\log(\mathrm{CometSunDistance})
\end{equation}

The term \texttt{slope\_parameter} may be a misnomer in case of
comets. From the literature \citep{AstronomicalAlgorithms:1998} (equation 33.13) we find
\begin{equation}
  \label{eq:comet_magnitudes_Meeus}
  \mathrm{mag}=g+5\log\Delta + \kappa\log r
\end{equation}
from which $\kappa=2\cdot\mathtt{slope\_parameter}$. In any case, $\kappa$ is typically [5\ldots15] and specific for each comet.

\begin{description}
\item[albedo] is used to set the brightness for rendering the body,
if you are close enough. 
\end{description}

A large number of elements for historical comets is provided in the
file \file{ssystem\_1000comets.ini} in the installation directory. You
can copy\&paste what you need into your
\file{ssystem\_minor.ini} or add all with the Solar System Editor plugin (section~\ref{sec:plugins:SolarSystemEditor}). 


With a clever combination of elements and \texttt{orbit\_good}
entries, \newFeature{0.21.3} it is possible to specify several sets of
orbital elements for different epochs of one apparition.

\paragraph{Periodic Comet}
\label{sec:ssystem.ini:Comet:Periodic}

\begin{configfile}
[1phalley]
type=comet  
name=1P/Halley

coord_func=kepler_orbit [can be omitted]
parent=Sun [can be omitted]
orbit_ArgOfPericenter=111.7154
orbit_AscendingNode=58.8583
orbit_Eccentricity=0.968004
orbit_Inclination=162.2453
orbit_PericenterDistance=0.57136
orbit_TimeAtPericenter=2446463.12979167
orbit_good=780

color=1.0, 1.0, 1.0
dust_brightnessfactor=1.5
dust_lengthfactor=0.4
dust_widthfactor=1.5

albedo=0.1
radius=5
absolute_magnitude=5.5
slope_parameter=3.2
tex_map=nomap.png
model=1682q1halley_MLfix.obj [optional]
\end{configfile}

You may want to e.g.\ change the name in this entry to
\texttt{name=1P/Halley (1982i)}. Note a rather short duration of
\texttt{orbit\_good}, which means the comet is only displayed 780 days
before and after perihelion. (Actually, before and after
\texttt{orbit\_Epoch}, but this is not given explicitly, so it
defaults to \texttt{orbit\_TimeAtPericenter}.)

Some comets have been visited by spacecraft so that shape models of their cores 
may be available and can be configured with a \texttt{model} entry.\newFeature{0.16.0}

\paragraph{Parabolic/Hyperbolic Comet}
\label{sec:ssystem.ini:Comet:Parabolic}

\begin{configfile}
[c2013us10%28catalina%29]
type=comet
name=C/2013 US10 (Catalina)

coord_func=kepler_orbit [can be omitted]
parent=Sun [can be omitted]
orbit_ArgOfPericenter=340.3533
orbit_AscendingNode=186.141
orbit_Eccentricity=1.000372
orbit_Inclination=148.8766
orbit_PericenterDistance=0.822958
orbit_TimeAtPericenter=2457342.20748843
orbit_good=1000

color=1.0, 1.0, 1.0
dust_brightnessfactor=1.5
dust_lengthfactor=0.4
dust_widthfactor=1.5

albedo=0.1
radius=5
absolute_magnitude=4.4
slope_parameter=4
tex_map=nomap.png
\end{configfile}

This has basically the same format. Note that eccentricity is larger than 1,
this means the comet is following a slightly hyperbolic
orbit. Stellarium shows data for this comet for almost 3 years
(\texttt{orbit\_good=1000} days) from the epoch (defaults to pericenter time).




%%% Local Variables: 
%%% mode: latex
%%% TeX-PDF-mode: t
%%% TeX-master: "guide"
%%% End: