Clarify default environment settings and SPICE

docs/source/_src_getting_started/quickstart.rst

@@ -23,7 +23,7 @@ The TU Delft Astrodynamics Toolbox (Tudat) is a powerful set of libraries that s
 Installation
 ************
 
-TudatPy is distributed as a ``conda`` package. To install it, download this ``environment.yaml`` (:download:`yaml <_static/environment.yaml>`). Then, in your terminal navigate to the directory containing this file and execute the following command:
+TudatPy is distributed as a ``conda`` package. To install it, download this ``environment.yaml`` file (:download:`yaml <_static/environment.yaml>`). Then, in your terminal navigate to the directory containing this file and execute the following command:
 
 .. code:: bash
 
@@ -254,7 +254,7 @@ Lastly, we define the termination conditions for the propagation, which in this
    fixed_step_size = 10.0
    integrator_settings = propagation_setup.integrator.runge_kutta_4(fixed_step_size)
 
-   propagator_type = propagation_setup.propagator.
+   propagator_type = propagation_setup.propagator.cowell
 
    # Create termination settings
    termination_settings = propagation_setup.propagator.time_termination(simulation_end_epoch)
@@ -411,12 +411,16 @@ We use the epochs to extract a subset of 3 hours of data, for which we plot the
 
    fig, ax = plt.subplots(tight_layout=True)
 
-   # Extract 3 hours data subset
-   time_hours = dependent_variables_array[:, 0] / 3600
    latitude = dependent_variables_array[:, 1]
    longitude = dependent_variables_array[:, 2]
-   hours = 3
-   subset = int(len(time_hours) / 24 * hours)
+
+   # Extract 3 hours data subset
+   relative_time_hours = (dependent_variables_array[:, 0] - simulation_start_epoch) / 3600
+   hours_to_extract = 3
+   propagation_span_hours = (simulation_end_epoch - simulation_start_epoch) / 3600
+
+   subset = int(len(relative_time_hours) / propagation_span_hours * hours_to_extract)
+
    latitude = np.rad2deg(latitude[:subset])
    longitude = np.rad2deg(longitude[:subset])
 

docs/source/_src_user_guide/state_propagation/environment_setup.rst

@@ -30,8 +30,8 @@ In Tudat, the physical environment is defined by a set of bodies, each encapsula
 (gravity field, ephemeris, *etc.*), which may be interdependent.
 
 .. note::
-   The :class:`~tudatpy.numerical_simulation.environment.Body` object may represent a celestial body or a
-   manmade vehicle. Tudat makes *no* a priori distinction between the two: the distinction is made by the user when
+   The :class:`~tudatpy.numerical_simulation.environment.Body` object may represent a celestial body or an
+   artificial vehicle. Tudat makes *no* a priori distinction between the two: the distinction is made by the user when
    creating the bodies.
 
 The combination of all Body objects is stored in a
@@ -46,8 +46,7 @@ it is also used to define properties of celestial bodies in, for instance, (semi
 (see :ref:`transfer_trajectory`).
 
 There are many different types of environment models in Tudat. See :ref:`available_environment_models` for
-a comprehensive list, and :ref:`specific_environment_considerations` for a number of overall considerations on
-specific types of environment models. The overall architecture of the environment in Tudat is described in more
+a comprehensive list. The overall architecture of the environment in Tudat is described in more
 detail on a dedicated page on :ref:`environment_architecture`.
 
 Body Creation - Procedure

docs/source/_src_user_guide/state_propagation/environment_setup/creation_celestial_body_settings.rst

@@ -4,7 +4,7 @@
 Creating the bodies
 ===================
 
-The usual workflow to create bodies in Tudat (both natural and manmade bodies!) is composed of three subsequent steps, described separately:
+The usual workflow to create bodies in Tudat (both natural and artificial bodies!) is composed of three subsequent steps, described separately:
 
 1. :ref:`default_body_settings`
 2. :ref:`custom_body_settings`
@@ -255,7 +255,7 @@ The example below shows how to create a set of bodies, using the :func:`~tudatpy
 
 
 The :class:`~tudatpy.numerical_simulation.environment.SystemOfBodies` class (the type of the ``bodies`` variable in the above simulation) is at the heart of many Tudat simulations. It contains all
-properties of your celestial and manmade bodies, and is used to retrieve properties of your accelerations, state derivative models, output
+properties of your celestial and artificial bodies, and is used to retrieve properties of your accelerations, state derivative models, output
 variables, etc. A more detailed discussion of the architecture of the :class:`~tudatpy.numerical_simulation.environment.Body` and :class:`~tudatpy.numerical_simulation.environment.SystemOfBodies` classes, as well as their constituent environment models and possible interdependencies, are discussed :ref:`here <environment_architecture>`
 
 It is crucial to understand the distinction between ``body_settings`` (of type :class:`~tudatpy.numerical_simulation.environment_setup.BodyListSettings`) and ``bodies`` (of type :class:`~tudatpy.numerical_simulation.environment.SystemOfBodies`). The former is merely a list of

docs/source/_src_user_guide/state_propagation/environment_setup/custom_models.rst

@@ -46,12 +46,12 @@ In each case, the user is required to define their own function, with a predefin
 
 The latter choice permits complex guidance algorithms to be implemented, in which (for instance) the algorithm for the control surface deflection, thrust magnitude and body-fixed thrust direction (thrust vector control) are calculated in a coupled manner.
 
-For most environment models, the custom model can be fully defined by a standalone function , and can be fully defined by a free function (which may of course call other functions from tudat, other packages or your own code. A custom function will, in numerous cases, have to depend on properties of bodies (states, altitude, density, etc.). How to access such properties of the environment *during* the propagation is described on the page on :ref:`environment_during_propagation`.
+For most environment models, the custom model can be fully defined by a standalone function , and can be fully defined by a free function (which may of course call other functions from tudat, other packages or your own code). A custom function will, in numerous cases, have to depend on properties of bodies (states, altitude, density, etc.). How to access such properties of the environment *during* the propagation is described on the page on :ref:`environment_during_propagation`.
 
 Custom model, free function
 ===========================
 
-Here, we show an example of an ephemeris model that will be both faster, and less accurate, than the models implemented in Tudat. This may be advantageous for preliminary simulation. The model is very simple: a perfectly circular orbit in the :math:`xy-`plane of the ``ECLIPJ2000`` frame.
+Here, we show an example of an ephemeris model that will be both faster, and less accurate, than the models implemented in Tudat. This may be advantageous for preliminary simulation. The model is very simple: a perfectly circular orbit in the :math:`xy-` plane of the ``ECLIPJ2000`` frame.
 
     .. tabs::
 
@@ -61,7 +61,7 @@ Here, we show an example of an ephemeris model that will be both faster, and les
              :language: python
 
 
-In the above example, the user-define function ``neptune_state_function`` is provided when creating the custom ephemeris settings. The only requirement on this custom function is that it takes a single float as argument (representing time since J2000), and returns a 6-dimensional vector (representing the Cartesian state in the frame specified), as can be seen in the :func:`~tudatpy.numerical_simulation.environment_setup.ephemeris.custom` API entry.
+In the above example, the user-defined function ``neptune_state_function`` is provided when creating the custom ephemeris settings. The only requirement on this custom function is that it takes a single float as argument (representing time since J2000), and returns a 6-dimensional vector (representing the Cartesian state in the frame specified), as can be seen in the :func:`~tudatpy.numerical_simulation.environment_setup.ephemeris.custom_ephemeris` API entry.
 
 .. _single_custom_models:
 

docs/source/_src_user_guide/state_propagation/environment_setup/default_env_models.rst

@@ -16,12 +16,15 @@ Default environment models
 
    default_env_models/default_bodies_limited_time_range 
 
+.. contents:: Content of this page
+   :local:
 
 To facilitate the creation of the celestial bodies in your simulation, Tudat provides the option of loading default
 models for a broad range of solar system bodies.
 
-.. contents:: Content of this page
-   :local:
+.. seealso::
+
+   For more information on how to create bodies in Tudat and modify their settings, see :ref:`creation_celestial_body_settings`. For a full example of how to setup a simulation environment with default settings, see the `perturbed satellite orbit example <../../../_src_getting_started/_src_examples/notebooks/propagation/perturbed_satellite_orbit.html>`_.
 
 Many of these settings are derived from so-called SPICE kernels. `SPICE <https://naif.jpl.nasa.gov/naif/toolkit.html>`_
 is a toolkit developed by NASA's Navigation and Ancillary Information Facility (NAIF) and is used throughout the space
@@ -31,18 +34,18 @@ with pre-defined ephemerides and rotation models of solar system bodies (see sec
 Default settings
 =================
 
-Using the data from these SPICE kernels into Tudat, the following default models
-are used by Tudat when calling the :func:`~tudatpy.interface.spice.load_standard_kernels` function.
+The default body settings are retrieved when calling the :func:`~tudatpy.numerical_simulation.environment_setup.get_default_body_settings` function in combination with calling :func:`~tudatpy.interface.spice.load_standard_kernels` beforehand.
+The following settings are then used for the default celestial bodies by Tudat.
 
 Ephemeris
 ---------
 
 Directly from SPICE (see :ref:`spice_in_tudat`). For our default settings, this includes all solar system
-planets, the Sun, Earth's moon, the main Martian, Jovian and Saturnian satellites. as well as 300 major solar system asteroids. Users can append this list with additional ephemeris files, for
+planets, the Sun, Earth's moon, the main Martian, Jovian and Saturnian satellites, as well as 300 major solar system asteroids. Users can append this list with additional ephemeris files, for
 instance for small bodies or other satellite systems, through the use of the
 :func:`~tudatpy.interface.spice.load_kernel`.
 
-Ephemerides from SPICE kernels are only valid for a somewhat limited time interval (on the order of one or several centuries, depending on the specific body), which is limited by the valid range of the SPICE kernels provided in Tudat by default. You can load additional SPICE kernels with a longer coverage by using the :func:`~tudatpy.interface.spice.load_kernel` function for any additional kernels you like (see, for instance, the `generic kernels <https://naif.jpl.nasa.gov/naif/data_generic.html>`_ listed on the SPICE website. Note that the contents will override data in the default kernels (if applicable).
+Ephemerides from SPICE kernels are only valid for a somewhat limited time interval (on the order of one or several centuries, depending on the specific body), which is limited by the valid range of the SPICE kernels provided in Tudat by default. You can load additional SPICE kernels with a longer coverage by using the :func:`~tudatpy.interface.spice.load_kernel` function for any additional kernels you like (see, for instance, the `generic kernels <https://naif.jpl.nasa.gov/naif/data_generic.html>`_ listed on the SPICE website or the `JPL Horizons System <https://ssd.jpl.nasa.gov/horizons/app.html#/>`_ for small-body objects). Note that the contents will override data in the default kernels (if applicable).
 
 .. note::
    In some cases, the extraction of the state of bodies from SPICE kernels can be a computational bottleneck. Tudat has an :ref:`alternative set of default options <default_bodies_limited_time_range>`, which make this process significantly faster, at the expense of higher RAM usage, and an environment that is only valid over a very limited time interval.
@@ -86,6 +89,9 @@ Gravity field
   (for any body available through SPICE kernels).
 
 .. warning::
+   For the bodies with default spherical harmonic gravity fields, the gravitational parameter is not loaded from SPICE, but is set to the value used in the construction of the gravity field model. This value may be different from the value used in the SPICE kernels, which you can retrieve using the :func:`~tudatpy.interface.spice.get_body_gravitational_parameter` function.
+
+.. seealso::
    Temporal variations of the gravity field are zero by default, but can be included for high-accuracy
    applications. See `API reference <https://py.api.tudat.space/en/latest/gravity_field_variation.html#functions>`_
 
@@ -109,11 +115,12 @@ SPICE in Tudat
 ===============
 
 The ``cspice`` toolkit (version of SPICE written in the C language) is included in the conda environment when installing
-Tudat, and Tudat contains a number of functions to directly interact with SPICE, listed `here <https://py.api.tudat.space/en/latest/spice.html>`_.
-
-The SPICE toolkit has extensive `lessons <https://naif.jpl.nasa.gov/naif/lessons.html>`_, `tutorials <https://naif.jpl.nasa.gov/naif/tutorials.html>`_ and  `detailed documentation <https://naif.jpl.nasa.gov/naif/documentation.html>`_.
+Tudat.
+The SPICE toolkit itself has extensive `lessons <https://naif.jpl.nasa.gov/naif/lessons.html>`_, `tutorials <https://naif.jpl.nasa.gov/naif/tutorials.html>`_ and  `detailed documentation <https://naif.jpl.nasa.gov/naif/documentation.html>`_.
+Tudat contains a number of functions to directly interact with SPICE, listed `here <https://py.api.tudat.space/en/latest/spice.html>`_.
 
 SPICE relies on a set of user-supplied input files (kernels) to perform its calculations. A number of these kernels are installed automatically with Tudat, and loaded when calling the :func:`~tudatpy.interface.spice.load_standard_kernels` function (see this API docs entry for list of kernels).
+To extend the standard kernels, a user can download additional kernels from other sources such as `NAIF directly <https://naif.jpl.nasa.gov/naif/data_generic.html>`_ or the `JPL Horizons System <https://ssd.jpl.nasa.gov/horizons/app.html#/>`_ for small-body objects, and then load them using the :func:`~tudatpy.interface.spice.load_kernel` function.
 
 When using the default kernels/body settings, we have introduced one small difference for the sake of expediency. For the cases of Uranus, Neptune and Pluto, where we only have the ephemeris of the barycenter of the planetary system loaded, the planet is placed at the barycenter of the planetary system. This introduces a minor offset in the position of this planet (Mercury and Venus have no moons, and therefore their state coincides with their planetary system barycenter; dedicated planetary system ephemerides are loaded for the Earth, Mars, Jupiter and Saturn system). For Uranus, for example, the default settings will place Uranus at the center of mass (barycenter) of the combined system of Uranus and its moons. To correct this behaviour, a user can load a kernel for this body's planetary system (see `here <https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/satellites/>`__, for example), and modify the default settings.
 

docs/source/_src_user_guide/state_propagation/environment_setup/default_env_models/default_bodies_limited_time_range.rst

@@ -24,7 +24,7 @@ The regular default body settings use the SPICE toolbox to determine the ephemer
           .. literalinclude:: /_src_snippets/simulation/environment_setup/req_create_bodies.cpp
              :language: cpp
 
-The difference w.r.t. the `regular creation<creation_celestial_body_settings>` of default body settings being the use of the :func:`~tudatpy.numerical_simulation.environment_setup.get_default_body_settings_time_limited` function (instead of :func:`~tudatpy.numerical_simulation.environment_setup.get_default_body_settings`). What is done when using this alternative setup:
+The difference w.r.t. the :ref:`regular creation <creation_celestial_body_settings>` of default body settings being the use of the :func:`~tudatpy.numerical_simulation.environment_setup.get_default_body_settings_time_limited` function (instead of :func:`~tudatpy.numerical_simulation.environment_setup.get_default_body_settings`). What is done when using this alternative setup:
 
  * When *creating* the bodies, SPICE is queried at a linearly spaced set of times (defined by the ``initial_time``, ``final_time`` and ``time_step``, the latter of which has a default of 300 s), resulting in a table of states for each body that is to be created
  * A 6-point :func:`~tudatpy.math.interpolators.lagrange_interpolation` is created for each body using these tables of states, and is used to define the ephemeris of the body

docs/source/_src_user_guide/state_propagation/environment_setup/environment_models.rst

@@ -25,7 +25,7 @@ Below, we provide an overview of the different types of environment models for w
 Available Model Types
 =====================
 
-The complete list of available environment model settings can be found on our API documentation. Below is a list with the different categories of models, and a link to the corresponding Tudatpy module
+The complete list of available environment model settings can be found on our API documentation. Below is a list with the different categories of models, and a link to the corresponding Tudatpy module:
 
 * `Aerodynamic coefficients <https://py.api.tudat.space/en/latest/aerodynamic_coefficients.html>`_, to be assigned to the :attr:`~tudatpy.numerical_simulation.environment_setup.BodySettings.aerodynamic_coefficient_settings` attribute of :class:`~tudatpy.numerical_simulation.environment_setup.BodySettings`. 
 
@@ -38,7 +38,7 @@ The complete list of available environment model settings can be found on our AP
    * The resulting model can be extracted from the :class:`~tudatpy.numerical_simulation.environment.Body` object using :attr:`~tudatpy.numerical_simulation.environment.Body.atmosphere_model`, which provides a :class:`~tudatpy.numerical_simulation.environment.AtmosphereModel`
 
 
-* `Ephemeris models <https://py.api.tudat.space/en/latest/ephemeris.html>`_, , to be assigned to the :attr:`~tudatpy.numerical_simulation.environment_setup.BodySettings.ephemeris_settings` attribute of :class:`~tudatpy.numerical_simulation.environment_setup.BodySettings`.  
+* `Ephemeris models <https://py.api.tudat.space/en/latest/ephemeris.html>`_, to be assigned to the :attr:`~tudatpy.numerical_simulation.environment_setup.BodySettings.ephemeris_settings` attribute of :class:`~tudatpy.numerical_simulation.environment_setup.BodySettings`.  
 
    * These models provide various ways in which to define predetermined (e.g. not coming from a Tudat propagation) translational states of bodies in the solar system
    * The resulting model can be extracted from the :class:`~tudatpy.numerical_simulation.environment.Body` object using :attr:`~tudatpy.numerical_simulation.environment.Body.ephemeris`, which provides a :class:`~tudatpy.numerical_simulation.environment.Ephemeris`