improving docs

.github/workflows/pykep.yml

@@ -17,7 +17,7 @@ jobs:
         run: bash tools/gha_linux_pykep.sh
       - name: Upload to github pages 🚀
         if: ${{ github.event_name == 'push' }}
-        uses: JamesIves/[email protected]
+        uses: JamesIves/[email protected] #workaround to be fixed upstream
         with:
           folder: doc/_build/html # The folder the action should deploy.
   windows_pykep:

doc/epoch.rst

@@ -4,7 +4,7 @@ Epoch class
 ################
 
 The representation of an epoch, that is of a specific point in time, be it in the future or in the past, can be rather confusing. 
-In `pykep` we opted to offer a dedicated class called :class:`~pykep.epoch`` to offer a simple interface and, under the hoods, interfacing
+In `pykep` we opted to offer a dedicated class called :class:`~pykep.epoch` to offer a simple interface and, under the hoods, interfacing
 seamlessly both to the c++ `std::chrono <https://en.cppreference.com/w/cpp/header/chrono>`_ 
 library and to the python `datetime <https://docs.python.org/3/library/datetime.html>`_ module. 
 

doc/refs.bib

@@ -63,4 +63,40 @@ @article{pagmo
   number={53},
   pages={2338},
   year={2020}
+}
+
+@article{terrile2005evolutionary,
+  title={Evolutionary computation technologies for the automated design of space systems},
+  author={Terrile, Richard J and Aghazarian, Hrand and Ferguson, Michael I and Fink, Wolfgang and Huntsberger, Terrance L and Keymeulen, Didier and Klimeck, Gerhard and Kordon, Mark A and Lee, Seungwon and von Allmen, Paul},
+  journal={2005 NASA/DoD Conference on Evolvable Hardware (EH'05)},
+  pages={131--138},
+  year={2005},
+  organization={IEEE}
+}
+
+@article{petropoulos2018gtoc9,
+  title={{GTOC9: Methods and results from the Jet Propulsion Laboratory team}},
+  author={Petropoulos, Anastassios and Grebow, Daniel and Jones, Drew and Lantoine, Gregory and Nicholas, Austin and Roa, Javier and Senent, Juan and Stuart, Jeffrey and Arora, Nitin and Pavlak, Thomas and others},
+  journal={Acta Futura},
+  volume={11},
+  pages={25--35},
+  year={2018}
+}
+
+@article{izzo2013search,
+  title={Search for a grand tour of the jupiter galilean moons},
+  author={Izzo, Dario and Simoes, Luis F and Martens, Marcus and de Croon, Guido CHE and Heritier, Aurelie and Yam, Chit Hong},
+  journal={Proceedings of the 15th annual conference on Genetic and evolutionary computation},
+  pages={1301--1308},
+  year={2013}
+}
+
+@article{izzo2010global,
+  title={Global optimization and space pruning for spacecraft trajectory design},
+  author={Izzo, Dario},
+  journal={Spacecraft Trajectory Optimization},
+  volume={1},
+  pages={178--200},
+  year={2010},
+  publisher={Cambridge University Press, New York, NY, USA}
 }

doc/taylor_adaptive.rst

@@ -4,7 +4,7 @@ Taylor adaptive propagators
 ############################
 
 
-Taylot adaptive integrators are offered in `pykep` wrapping some of the functionalities of
+Taylor adaptive integrators are offered in `pykep` wrapping some of the functionalities of
 `Heyoka <https://bluescarni.github.io/heyoka.py/index.html>`_ :cite:p:`biscaniheyoka1` python package.
 Their variational version is also offered (at order one) as to be able to produce stms and, where needed,
 more. Higher order variational equations can also be obtained directly using the available dynamics and 

doc/trajopt.rst

@@ -3,10 +3,11 @@
 Trajectory Optimization
 ###########################
 
-In `pykep` both direct and indirect optimization techniques are provided
-to perform spacecraft trajectory optimization. Most direct techniques provided are
+In `pykep` both direct and indirect optimization transcriptions as well as evolutionary encodings
+are provided to perform spacecraft trajectory optimization. Most direct techniques provided are
 based on the "Sims" transcription :cite:p:`sims`, while indirect techniques are based on some
-version of Pontryagin Maximum Principle.
+version of Pontryagin Maximum Principle. The evolutionary encoding are mostly based on the work
+performed at `ESA' Advanced Concepts Team <https://www.esa.int/gsp/ACT/>`_ (:cite:p:`izzo2010global`, :cite:p:`izzo2013search`).
 
 Most of the classes in this Trajectory Optimization module are provided as
 optimization problems (NLP) compatible to the pagmo software suite.
@@ -15,6 +16,15 @@ optimization problems (NLP) compatible to the pagmo software suite.
 
 Direct
 ************************
+When solving optimal control problems (OCPs), the unknown is a function (i.e. the control), 
+hence one is dealing with an infinite dimensional search space.
+A common approach to overcome this difficulty is to use direct methods. 
+These are based on the idea of discretizing the problem introducing some time grid
+and thus transforming the OCP into a NLP (Non Linear Programming) problem
+to then solve it using numerical solvers available for the task.
+
+-------------------------------------------------------
+
 .. autoclass:: direct_point2point
     :members: pretty, plot
 
@@ -23,4 +33,19 @@ Direct
 .. autoclass:: direct_pl2pl
     :members: pretty, plot
 
+-------------------------------------------------------
+
+Evolutionary Encodings
+************************
+Some type of interplanetary trajectories can be *evolved*: shocking?. 
+This AI approach to trajectory design resulted in two silver (:cite:p:`terrile2005evolutionary`, :cite:p:`petropoulos2018gtoc9`) 
+and one gold (:cite:p:`izzo2013search`)
+`Humies award <https://www.human-competitive.org>`_  for human-competitive
+results that were produced by any form of genetic and evolutionary computation.
+In `pykep` we offer some classes that help instantiating these type of transfers
+amenable to evolutionary techniques.
+
+-------------------------------------------------------
 
+.. autoclass:: mga
+    :members: pretty, plot, to_planet

pykep/trajopt/_direct_pl2pl.py

@@ -38,8 +38,7 @@ def __init__(
         v_scaling=_pk.EARTH_VELOCITY,
         with_gradient=True,
     ):
-        """
-        Initializes the direct_pl2pl instance with given parameters.
+        """direct_pl2pl(pls, plf, ms = 1500, mu=_pk.MU_SUN, max_thrust=0.12, isp=3000, t0_bounds=[6700.0, 6800.0], tof_bounds=[200.0, 300.0], mf_bounds=[1300.0, 1500.0], vinfs=3.0, vinff=0.0, nseg=10, cut=0.6, mass_scaling=1500, r_scaling=pk.AU, v_scaling=pk.EARTH_VELOCITY, with_gradient=True)
 
         Args:
             *pls* (:class:`~pykep.planet`): Initial planet. Defaults to jpl_lp Earth.
@@ -255,7 +254,7 @@ def get_nic(self):
 
     def pretty(self, x):
         """
-        Prints a humar readable representation of the transfer.
+        Prints a human readable representation of the transfer.
 
         Args:
             *x* (:class:`list`): The decision vector containing final mass, thrust direction, and time of flight.
@@ -295,26 +294,26 @@ def plot(
     ):
         """
         Plots the trajectory leg  3D axes.
-        
+
         Args:
             *x* (:class:`list`): The decision vector containing final mass, thrust direction, and time of flight.
-            
+
             *ax* (:class:`mpl_toolkits.mplot3d.axes3d.Axes3D`, optional): The 3D axis to plot on. Defaults to None.
-            
+
             *units* (:class:`float`, optional): The unit scale for the plot. Defaults to _pk.AU.
-            
+
             *show_midpoints* (:class:`bool`, optional): Whether to show midpoints on the trajectory. Defaults to False.
-            
+
             *show_gridpoints* (:class:`bool`, optional): Whether to show grid points on the trajectory. Defaults to False.
-            
+
             *show_throttles* (:class:`bool`, optional): Whether to show throttle vectors. Defaults to False.
-            
+
             *length* (:class:`float`, optional): Length of the throttle vectors. Defaults to 0.1.
-            
+
             *arrow_length_ratio* (:class:`float`, optional): Arrow length ratio for the throttle vectors. Defaults to 0.05.
-            
+
             *\*\*kwargs*: Additional keyword arguments for the plot.
-            
+
         Returns:
             :class:`mpl_toolkits.mplot3d.axes3d.Axes3D`: The 3D axis with the plotted trajectory.
         """

pykep/trajopt/_mga.py

@@ -6,30 +6,32 @@
 
 
 class mga:
-    r"""
-    The Multiple Gravity Assist (MGA) encoding of an interplanetary trajectory.
+    r"""The Multiple Gravity Assist (MGA) encoding of an interplanetary trajectory.
 
     This class may be used as a User Defined Problem (UDP) for the pygmo (http://esa.github.io/pygmo/) optimisation suite.
 
-    - Izzo, Dario. "Global optimization and space pruning for spacecraft trajectory design." Spacecraft Trajectory Optimization 1 (2010): 178-200.
-
     The decision vector (chromosome) is::
 
-      direct encoding: [t0, T1, T2 ... ] in [mjd2000, days, days ... ]
-      alpha encoding:  [t0, T, a1, a2 ...] in [mjd2000, days, nd, nd ... ]
-      eta encoding:    [t0, n1, n2, n3 ...] in [mjd2000, nd, nd ...]
+      direct encoding: z = [t0, T1, T2 ... ] in [mjd2000, days, days ... ]
+      alpha encoding: z = [t0, T, a1, a2 ...] in [mjd2000, days, nd, nd ... ]
+      eta encoding: z = [t0, n1, n2, n3 ...] in [mjd2000, nd, nd ...]
 
     .. note::
 
        The time of flights of a MGA trajectory (and in general) can be encoded in different ways.
-       When they are directly present in the decision vector, we have the *direct* encoding. This is the most 'evolvable' encoding
-       but also the one that requires the most problem knowledge (e.g. to define the bounds on each leg) and is not
-       very flexible in dealing with constraints on the total time of flight. The *alpha* and *eta* encodings, instead, allow
-       to only specify bounds on the time of flight of the entire trajectory, and not on the single legs: a property that is attractive
-       for multi-objective optimization, for example.
+       When they are directly present in the decision vector, we talk about a *direct* encoding. This is the most
+       'evolvable' encoding but also the one that requires the most problem knowledge (e.g. to define the bounds on each leg)
+       and is not very flexible in dealing with constraints on the total time of flight. The *alpha* and *eta* encodings,
+       instead, allow to only specify bounds on the time of flight of the entire trajectory, and not on the single legs:
+       a property that is attractive for multi-objective optimization, for example.
+
+       In the *alpha* encoding each leg time-of-flight is decoded as follows,
+
+       :math:`T_i = T \log\alpha_i / \sum_n\log\alpha_n`.
 
-       In the *alpha* encoding each leg time-of-flight is decoded as follows, T_i = T log(alpha_i) / \sum_n(log(alpha_n)).
-       In the *eta* encoding  each leg time-of-flight is decoded as follows, T_i = (tof_max - \sum_0^(i-1)(T_j)) * eta_i
+       In the *eta* encoding  each leg time-of-flight is decoded as follows,
+
+       :math:`T_i = (T_{max} - \sum_{j=0}^{(i-1)}T_j) \eta_i`
 
        The chromosome dimension for the direct and eta encoding is the same, while the alpha encoding requires one more gene.
 
@@ -54,28 +56,31 @@ def __init__(
         e_target=None,
         rp_target=None,
     ):
-        r"""mga(seq, t0, tof, vinf, multi_objective=False, alpha_encoding=False, orbit_insertion=False, e_target=None, rp_target=None)
+        r"""mga(seq, t0, tof, vinf, multi_objective=False, tof_encoding="direct"", orbit_insertion=False, e_target=None, rp_target=None)
 
         Args:
-            - seq (``list of pk.planet``): sequence of body encounters including the departure planet.
-            - t0 (:class:`list` of :class:`float` or :class:`~pk.epoch`): lower and upper bounds for the launch epoch. When floats are used MJD2000 is assumed.
-            - tof (``list`` or ``float``): defines the bounds on the time of flight. If *tof_encoding* is 'direct', this contains a list
-              of 2D lists defining the upper and lower bounds on each leg. If *tof_encoding* is 'alpha',
-              this contains a 2D list with the lower and upper bounds on the total time-of-flight. If *tof_encoding*
-              is 'eta' tof is a float defining an upper bound for the time-of-flight.
-            - vinf (:class:`float`): the vinf provided at launch for free
-            - multi_objective (:class:`bool`): when True constructs a multiobjective problem (dv, T). In this case, 'alpha' or `eta` encodings are recommended
-            - tof_encoding (:class:`str`): one of 'direct', 'alpha' or 'eta'. Selects the encoding for the time of flights
-            - orbit_insertion (:class:`bool`): when True the arrival dv is computed as that required to acquire a target orbit defined by e_target and rp_target
-            - e_target (:class:`float`): if orbit_insertion is True this defines the target orbit eccentricity around the final planet
-            - rp_target (:class:`float`): if orbit_insertion is True this defines the target orbit pericenter around the final planet (in m)
-            - max_revs (:class:`int`): maximal number of revolutions for lambert transfer
+            *seq* (:class:`list` [:class:`~pykep.planet`]): sequence of planetary encounters including the departure body.
 
-        Raises:
-            - ValueError: if *planets* do not share the same central body (checked on the mu_central_body attribute)
-            - ValueError: if *t0* does not contain objects able to construct a epoch (e.g. pk. epoch or floats)
-            - ValueError: if *tof* is badly defined
-            - ValueError: it the target orbit is not defined and *orbit_insertion* is True
+            *t0* (:class:`list` [:class:`float` or :class:`~pk.epoch`]): lower and upper bounds for the launch epoch. When floats are used MJD2000 is assumed.
+
+            *tof* (``list`` or ``float``): defines the bounds on the time of flight. If *tof_encoding* is 'direct', this contains a list
+            of 2D lists defining the upper and lower bounds on each leg. If *tof_encoding* is 'alpha',
+            this contains a 2D list with the lower and upper bounds on the total time-of-flight. If *tof_encoding*
+            is 'eta' tof is a float defining an upper bound for the time-of-flight.
+
+            *vinf* (:class:`float`): the vinf provided at launch for free
+
+            *multi_objective* (:class:`bool`): when True constructs a multiobjective problem (dv, T). In this case, 'alpha' or `eta` encodings are recommended
+
+            *tof_encoding* (:class:`str`): one of 'direct', 'alpha' or 'eta'. Selects the encoding for the time of flights
+
+            *orbit_insertion* (:class:`bool`): when True the arrival dv is computed as that required to acquire a target orbit defined by e_target and rp_target
+
+            *e_target* (:class:`float`): if orbit_insertion is True this defines the target orbit eccentricity around the final planet
+
+            *rp_target* (:class:`float`): if orbit_insertion is True this defines the target orbit pericenter around the final planet (in m)
+
+            *max_revs* (:class:`int`): maximal number of revolutions for lambert transfer
         """
 
         # Sanity checks
@@ -345,14 +350,14 @@ def fitness(self, x):
 
     def to_planet(self, x: List[float]):
         """
-        For a decision vector *x*, constructs a virtual planet with the spacecraft ephemerides.
+        Returns a :class:`~pykep.planet` representing the spacecraft trajectory encoded into *x*.
 
         Args:
-            - x (``list``, ``tuple``, ``numpy.ndarray``): Decision chromosome, e.g. (``pygmo.population.champion_x``).
+            *x* (:class:`list`): The decision vector in the correct tof encoding.
 
         Example:
-          udpla = mga_udp.to_planet(population.champion_x)
-          r, v = udpla.eph(7000.)
+          sc = mga_udp.to_planet(population.champion_x)
+          r, v = sc.eph(7000.)
         """
 
         class mga_udpla:
@@ -413,12 +418,11 @@ def get_name(self):
         return _pk.planet(mga_udpla(self.seq, lambert_legs, mjd2000s))
 
     def pretty(self, x):
-        """pretty(x)
+        """
+        Prints a human readable representation of the transfer.
 
         Args:
-            - x (``list``, ``tuple``, ``numpy.ndarray``): Decision chromosome, e.g. (``pygmo.population.champion_x``).
-
-        Prints human readable information on the trajectory represented by the decision vector x
+            *x* (:class:`list`): The decision vector in the correct tof encoding.
         """
         DVlaunch, DVfb, DVarrival, lambert_legs, DVlaunch_tot, mjd2000s, T = (
             self._compute_dvs(x)
@@ -449,15 +453,22 @@ def pretty(self, x):
         print("\nTotal DV: ", DVlaunch + _np.sum(DVfb) + DVarrival)
 
     def plot(self, x, ax=None, units=_pk.AU, N=60, figsize=(5, 5)):
-        """plot(self, x, axes=None, units=pk.AU, N=60)
-
-        Plots the spacecraft trajectory.
+        """
+        Plots the trajectory leg  3D axes.
 
         Args:
-            - x (``tuple``, ``list``, ``numpy.ndarray``): Decision chromosome.
-            - axes (``matplotlib.axes._subplots.Axes3DSubplot``): 3D axes to use for the plot
-            - units (``float``, ``int``): Length unit by which to normalise data.
-            - N (``float``): Number of points to plot per leg
+            *x* (:class:`list`): The decision vector in the correct tof encoding.
+
+            *ax* (:class:`mpl_toolkits.mplot3d.axes3d.Axes3D`, optional): The 3D axis to plot on. Defaults to None.
+
+            *units* (:class:`float`, optional): The unit scale for the plot. Defaults to pk.AU.
+
+            *N* (:class:`int`, optional): The number of points to use when plotting the trajectory. Defaults to 60.
+
+            *figsize* (:class:`tuple`): The figure size (only used if a*ax* is None and axis ave to be created.), Defaults to (5, 5).
+
+        Returns:
+            :class:`mpl_toolkits.mplot3d.axes3d.Axes3D`: The 3D axis where the trajectory was plotted.
         """
         import matplotlib.pyplot as plt