format + docs

doc/api.rst

@@ -10,3 +10,42 @@ $\partial$SGP4 API
    :recursive:
 
    dsgp4
+   dsgp4.plot.plot_orbit
+   dsgp4.plot.plot_tles
+   dsgp4.tle.compute_checksum
+   dsgp4.tle.read_satellite_catalog_number
+   dsgp4.tle.load_from_lines
+   dsgp4.tle.load_from_data
+   dsgp4.tle.load
+   dsgp4.tle.TLE
+   dsgp4.tle.TLE.copy
+   dsgp4.tle.TLE.perigee_alt
+   dsgp4.tle.TLE.apogee_alt
+   dsgp4.tle.TLE.set_time
+   dsgp4.tle.TLE.update
+   dsgp4.util.get_gravity_constants
+   dsgp4.util.propagate_batch
+   dsgp4.util.propagate
+   dsgp4.util.initialize_tle
+   dsgp4.util.from_year_day_to_date
+   dsgp4.util.gstime
+   dsgp4.util.clone_w_grad
+   dsgp4.util.jday
+   dsgp4.util.invjday
+   dsgp4.util.days2mdhms
+   dsgp4.util.from_string_to_datetime
+   dsgp4.util.from_mjd_to_epoch_days_after_1_jan
+   dsgp4.util.from_mjd_to_datetime
+   dsgp4.util.from_jd_to_datetime
+   dsgp4.util.get_non_empty_lines
+   dsgp4.util.from_datetime_to_fractional_day
+   dsgp4.util.from_datetime_to_mjd
+   dsgp4.util.from_datetime_to_jd
+   dsgp4.util.from_cartesian_to_tle_elements
+   dsgp4.util.from_cartesian_to_keplerian
+   dsgp4.util.from_cartesian_to_keplerian_torch
+   dsgp4.sgp4
+   dsgp4.sgp4_batched
+   dsgp4.sgp4init.sgp4init
+   dsgp4.sgp4init_batch.sgp4init_batch
+   dsgp4.sgp4init_batch.initl_batch

dsgp4/newton_method.py

@@ -31,14 +31,16 @@ def initial_guess(tle_0, time_mjd, target_state=None):
     This method takes an initial TLE and the time at which we want to propagate it, and returns
     a set of parameter related to an initial guess useful to find the TLE observation that corresponds to the propagated state
 
-    Args:
-        - tle_0 (``dsgp4.tle.TLE``): starting TLE at time0
-        - new_date (``datetime.datetime``): new date of the TLE, as a datetime object
-        - target_state (``torch.tensor``): a 2x3 tensor for the position and velocity of the state. If None, then this is computed 
+    Parameters:
+    ----------------
+    tle_0 (``dsgp4.tle.TLE``): starting TLE at time
+    new_date (``datetime.datetime``): new date of the TLE, as a datetime objec
+    target_state (``torch.tensor``): a 2x3 tensor for the position and velocity of the state. If None, then this is computed 
                                             by propagating `tle_0` at the `new_date`.
 
     Returns:
-        - y0 (``torch.tensor``): initial guess for the TLE elements. In particular, y0 contains
+    ----------------
+    y0 (``torch.tensor``): initial guess for the TLE elements. In particular, y0 contains
                                  the following elements (see SGP4 for a thorough description of these parameters):
                                 * y0[0]: bstar (B* parameter)
                                 * y0[1]: ndot (mean motion first derivative)
@@ -49,11 +51,14 @@ def initial_guess(tle_0, time_mjd, target_state=None):
                                 * y0[6]: mo (mean anomaly)
                                 * y0[7]: no_kozai (mean anomaly in certain units)
                                 * y0[8]: nodeo (right ascension of the ascending node)
-        - target_state (``torch.tensor``): this expresses the cartesian state as position & velocity in km & km/s, at the propagated time.
+                        
+                        target_state (``torch.tensor``): this expresses the cartesian state as position & velocity in km & km/s, at the propagated time.
                                             The objective of the Newton method is to find the TLE observation that corresponds to that, at the propagated
                                             time.
-        - new_tle (``dsgp4.tle.TLE``): TLE constructed with `y0`, in order to find the TLE that corresponds to `target_state`
-        - tle_elements_0 (``dict``): dictionary used to construct `new_tle`
+                                    
+                                    new_tle (``dsgp4.tle.TLE``): TLE constructed with `y0`, in order to find the TLE that corresponds to `target_state`
+                                    
+                                    tle_elements_0 (``dict``): dictionary used to construct `new_tle`
 
     """
     new_date=util.from_mjd_to_datetime(time_mjd)
@@ -115,12 +120,14 @@ def update_TLE(old_tle,y0):
     This method takes a TLE and an initial guess, and returns a TLE updated accordingly. It
     is useful while doing Newton iterations.
 
-    Args:
-        - old_tle (``dsgp4.tle.TLE``): TLE corresponding to previous guess
-        - y0 (``torch.tensor``): initial guess (see the docstrings for `initial_guess` to know the content of `y0`)
+    Parameters:
+    ----------------
+    old_tle (``dsgp4.tle.TLE``): TLE corresponding to previous guess
+    y0 (``torch.tensor``): initial guess (see the docstrings for `initial_guess` to know the content of `y0`)
 
     Returns:
-        - new_tle (``dsgp4.tle.TLE``): updated TLE
+    ----------------
+    new_tle (``dsgp4.tle.TLE``): updated TLE
 
     """
     tle_elements={}
@@ -155,16 +162,18 @@ def newton_method(tle_0, time_mjd, target_state=None, new_tol=1e-12,max_iter=50)
     This method performs Newton method starting from an initial TLE and a given propagation time. The objective 
     is to find a TLE that accurately reconstructs the propagated state, at observation time.
 
-    Args:
-        - tle_0 (``dsgp4.tle.TLE``): starting TLE (i.e., TLE at a given initial time)
-        - time_mjd (``float``): time at which we want to propagate the TLE (in Modified Julian Date)
-        - target_state (``torch.tensor``): a 2x3 tensor for the position and velocity of the state. If None, then this is computed by propagating `tle_0` at the `new_date`.
-        - new_tol (``float``): tolerance for the Newton method
-        - max_iter (``int``): maximum number of iterations for the Newton method
+    Parameters:
+    ----------------
+    tle_0 (``dsgp4.tle.TLE``): starting TLE (i.e., TLE at a given initial time)
+    time_mjd (``float``): time at which we want to propagate the TLE (in Modified Julian Date)
+    target_state (``torch.tensor``): a 2x3 tensor for the position and velocity of the state. If None, then this is computed by propagating `tle_0` at the `new_date`.
+    new_tol (``float``): tolerance for the Newton method
+    max_iter (``int``): maximum number of iterations for the Newton method
 
     Returns:
-        - next_tle (``dsgp4.tle.TLE``): TLE corresponding to the propagated state
-        - y0 (``torch.tensor``): initial guess for the TLE elements. In particular, y0 contains the following elements (see SGP4 for a thorough description of these parameters):
+    ----------------
+    next_tle (``dsgp4.tle.TLE``): TLE corresponding to the propagated state
+    y0 (``torch.tensor``): initial guess for the TLE elements. In particular, y0 contains the following elements (see SGP4 for a thorough description of these parameters):
 
     """
     i=0

dsgp4/plot.py

@@ -6,16 +6,18 @@ def plot_orbit(states, r_earth=6378.137, elevation_azimuth=None, ax=None, *args,
     """
     This function takes a tensor of states, and plots the orbit, together with the Earth.
 
-    Args:
-        - states (``torch.tensor``): a set of len(tsince)x2x3 tensor of states,  where the first row represents the spacecraft
-                                     position (in km) and the second the spacecraft velocity (in km/s). Reference frame is TEME.
-        - r_earth (``float``): Earth radius in km (used for the plot). Default value is 6378.137 km.
-        - elevation_azimuth (``tuple``): tuple of two floats, representing the elevation and azimuth angles of the plot. If None, the default values are used.
-        - ax (``matplotlib.axes._subplots.Axes3DSubplot``): 3D axis object. If None, a new figure is created.
-        - *args, **kwargs: additional arguments to be passed to the plot function
-    
+    Parameters:
+    ----------------
+    states (``torch.tensor``): a set of len(tsince)x2x3 tensor of states,  where the first row represents the spacecraft position (in km) and the second the spacecraft velocity (in km/s). Reference frame is TEME.
+    r_earth (``float``): Earth radius in km (used for the plot). Default value is 6378.137 km.
+    elevation_azimuth (``tuple``): tuple of two floats, representing the elevation and azimuth angles of the plot. If None, the default values are used.
+    ax (``matplotlib.axes._subplots.Axes3DSubplot``): 3D axis object. If None, a new figure is created.
+    args: additional arguments to be passed to the plot function.
+    kwargs: additional kwarguments to be passed to the plot function.
+
     Returns:
-        - ax (``matplotlib.axes._subplots.Axes3DSubplot``): 3D axis object
+    ----------------
+    ``matplotlib.axes._subplots.Axes3DSubplot``: 3D axis object
     """
     if ax is None:
         fig = plt.figure()
@@ -65,18 +67,21 @@ def plot_tles(tles,
     """
     This function takes a list of tles as input and plots the histograms of some of their elements.
     
-    Args:    
-        - tles (``list``): list of tles, where each element is a ``dsgp4.tle.TLE`` object.
-        - file_name (``str``): name of the file (including path) where the plot is to be saved.
-        - figsize (``tuple``): figure size.
-        - show (``bool``): if True, the plot is shown.
-        - axs (``numpy.ndarray``): array of AxesSubplot objects.
-        - return_axs (``bool``): if True, the function returns the array of AxesSubplot objects.
-        - log_yscale (``bool``): if True, the y-scale is logarithmic.
-        - *args, **kwargs: additional arguments to be passed to the hist function.
+    Parameters:
+    ----------------
+    tles (``list``): list of tles, where each element is a ``dsgp4.tle.TLE`` object.
+    file_name (``str``): name of the file (including path) where the plot is to be saved.
+    figsize (``tuple``): figure size.
+    show (``bool``): if True, the plot is shown.
+    axs (``numpy.array``): array of AxesSubplot objects.
+    return_axs (``bool``): if True, the function returns the array of AxesSubplot objects.
+    log_yscale (``bool``): if True, the y-scale is logarithmic.
+    args: additional arguments to be passed to the hist function.
+    kwargs: additional kwarguments to be passed to the hist function.
     
     Returns:    
-        - ax (``numpy.ndarray``): array of AxesSubplot objects
+    ----------------
+    ``numpy.array``: array of AxesSubplot objects
     """
     #I collect all the six variables from the TLEs:
     mean_motion, eccentricity, inclination, argument_of_perigee, raan, b_star, mean_anomaly, mean_motion_first_derivative, mean_motion_second_derivative = [], [], [], [], [], [], [], [], []

dsgp4/sgp4.py

@@ -10,13 +10,14 @@ def sgp4(satellite, tsince):
     to propagate the TLE at future times. The method returns the satellite position and velocity
     in km and km/s, respectively, after `tsince` minutes.
 
-    Args:
-        - satellite (``dsgp4.tle.TLE``): TLE object
-        - tsince (``int`` or ``float`` or ``list`` or ``torch.tensor``): time to propagate, since the TLE epoch, in minutes (can be a vector or a single element)
+    Parameters:
+    ----------------
+    satellite (``dsgp4.tle.TLE``): a TLE object.
+    tsince (``torch.tensor``): a torch.tensor of times since the TLE epoch in minutes.
 
     Returns:
-        - state (``torch.tensor``): a set of len(tsince)x2x3 tensor of states,  where the first row represents the spacecraft
-                                    position (in km) and the second the spacecraft velocity (in km/s). Reference frame is TEME.
+    ----------------
+    (``torch.tensor``): a tensor of len(tsince)x2x3 representing the satellite position and velocity in km and km/s, respectively.
     """
     #quick check to see if the satellite has been initialized
     if not isinstance(satellite, TLE):

dsgp4/sgp4_batched.py

@@ -11,12 +11,14 @@ def sgp4_batched(satellite_batch, tsince):
     The method returns the satellite position and velocity
     in km and km/s, respectively, after `tsince` minutes.
 
-    Args:
-        - satellite (``dsgp4.tle.TLE``): TLE batch object (with attributes that are N-dimensional tensors) 
-        - tsince (``torch.tensor``): time to propagate, since the TLE epoch, in minutes (also an N-dimensional tensor)
+    Parameters:
+    ----------------
+    satellite_batch (``dsgp4.tle.TLE``): a TLE object.
+    tsince (``torch.tensor``): a torch.tensor of times since the TLE epoch in minutes.
 
     Returns:
-        - batch_state (``torch.tensor``): a batch of 2x3 tensors, where the first row represents the spacecraft
+    ----------------
+    batch_state (``torch.tensor``): a batch of 2x3 tensors, where the first row represents the spacecraft
                                     position (in km) and the second the spacecraft velocity (in km/s)
     """
     if not isinstance(satellite_batch, TLE):