doc improvements

smrt/inputs/make_medium.py

@@ -58,8 +58,9 @@ def make_medium(data, surface=None, interface=None, substrate=None, **kwargs):
 
 ** Note **: `make_medium` create laters using all the columns in the dataframe. It means that any column name becomes an attribute of
  the layer objects, even if not recognized/used by SMRT. This can be seen as an interesting feature to store information in layers,
- but this is also dangerous if column names collide with internal layer attributes or method names. It is recommended to clean
- the dataframe (with df.drop(columns=[...])) before calling make_medium.
+ but this is also dangerous if column names collide with internal layer attributes or method names. For this reason,
+this function is unsecure if the snowpack data are pulled from the internet. Always check the content of the file, and it is recommended 
+to drop all the unnecessary columns with df.drop(columns=[...])) before calling make_medium. 
 
 """
 
@@ -434,8 +435,10 @@ def make_ice_layer(ice_type,
     :param density: (multiyear) density of ice layer in kg m :sup:`-3`. If not given, density is calculated from temperature,
         salinity and ice porosity.
     :param porosity: (mutliyear and fresh) air porosity of ice layer (0..1). Default is 0.
-    :param ice_permittivity_model: (all) pure ice permittivity formulation (default is ice_permittivity_matzler06)
-    :param brine_permittivity_model: (firstyear and multiyear) brine permittivity formulation (default is brine_permittivity_stogryn85)
+    :param ice_permittivity_model: (all) pure ice permittivity formulation 
+        (default is ice_permittivity_matzler06 for firstyear and fresh, and saline_ice_permittivity_pvs_mixing for multiyear)
+    :param brine_permittivity_model: (firstyear and multiyear) brine permittivity formulation 
+        (default is brine_permittivity_stogryn85)
     :param saline_ice_permittivity_model: (multiyear) model to mix ice and brine. The default uses polder van staten and
         ice_permittivity_model and brine_permittivity_model. It is highly recommanded to use the default.
     :param kwargs: other microstructure parameters are given as optional arguments (in Python words) but may be required (in SMRT words).

smrt/rtsolver/dort.py

@@ -34,27 +34,31 @@
 
 class DORT(object):
     """Discrete Ordinate and Eigenvalue Solver
-
-        :param n_max_stream: number of stream in the most refringent layer
-        :param m_max: number of mode (azimuth)
-        :param phase_normalization: the integral of the phase matrix should in principe be equal to the scattering coefficient.
+    
+    :param n_max_stream: number of stream in the most refringent layer
+    :param m_max: number of mode (azimuth)
+    :param phase_normalization: the integral of the phase matrix should in principe be equal to the scattering coefficient.
         However, some emmodels do not respect this strictly. In general a small difference is due to numerical rounding and is acceptable,
         but a large difference rather indicates either a bug in the emmodel or input parameters that breaks the
         assumption of the emmodel. The most typical case is when the grain size is too big compared to wavelength for emmodels
         that rely on Rayleigh assumption. If this argument is to True (the default), the phase matrix is normalized to be coherent
         with the scattering coefficient, but only when the difference is moderate (0.7 to 1.3).
         If set to "force" the normalization is always performed. This option is dangerous because it may hide bugs or unappropriate
         input parameters (typically too big grains). If set to False, no normalization is performed.
-        :param error_handling: If set to "exception" (the default), raise an exception in cause of error, stopping the code. If set to "nan", return a nan, so the calculation can continue, 
-        but the result is of course unusuable and the error message is not accessible. This is only recommended for long simulations that sometimes produce an error.
-        :param process_coherent_layers: Adapt the layers thiner than the wavelegnth using the MEMLS method. The radiative transfer theory is inadequate
-        layers thiner than the wavelength and using DORT with thin layers is generally not recommended. In some parcticular cases (such as ice lenses)
-        where the thin layer is isolated between large layers, it is possible to replace the thin layer by an equivalent reflective interface.
-        This neglects scattering in the thin layer, which is acceptable in most case, because the layer is thin. To use this option and more generally 
+    :param error_handling: If set to "exception" (the default), raise an exception in cause of error, stopping the code.
+        If set to "nan", return a nan, so the calculation can continue, but the result is of course unusuable and
+        the error message is not accessible. This is only recommended for long simulations that sometimes produce an error.
+    :param process_coherent_layers: Adapt the layers thiner than the wavelegnth using the MEMLS method. The radiative transfer
+        theory is inadequate layers thiner than the wavelength and using DORT with thin layers is generally not recommended.
+        In some parcticular cases (such as ice lenses) where the thin layer is isolated between large layers, it is possible
+        to replace the thin layer by an equivalent reflective interface. This neglects scattering in the thin layer,
+        which is acceptable in most case, because the layer is thin. To use this option and more generally
         to investigate ice lenses, it is recommended to read MEMLS documentation on this topic.
-        :param prune_deep_snowpack: this value is the optical depth from which the layers are discarded in the calculation. It is to be use to accelerate the calculations
-        for deep snowpacks or at high frequencies when the contribution of the lowest layers is neglegible. The optical depth is a good criteria to determine this limit.
+    :param prune_deep_snowpack: this value is the optical depth from which the layers are discarded in the calculation.
+        It is to be use to accelerate the calculations for deep snowpacks or at high frequencies when the 
+        contribution of the lowest layers is neglegible. The optical depth is a good criteria to determine this limit.
         A value of about 6 is recommended. Use with care, especially values lower than 6.
+
     """
 
     # this specifies which dimension this solver is able to deal with. Those not in this list must be managed by the called (Model object)
@@ -504,9 +508,9 @@ def dort_modem_banded(self, m, streams, eigenvalue_solver,
 
         if self.snowpack.substrate is None and optical_depth < 5:
             smrt_warn("DORT has detected that the snowpack is optically shallow (tau=%g) and no substrate has been set, meaning that the space "
-                 "under the snowpack is vaccum and that the snowpack is shallow enough to affect the signal measured at the surface."
-                 "This is usually not wanted. Either increase the thickness of the snowpack or set a substrate."
-                 " If wanted, add a transparent substrate to supress this warning" % optical_depth)
+                      "under the snowpack is vaccum and that the snowpack is shallow enough to affect the signal measured at the surface."
+                      "This is usually not wanted. Either increase the thickness of the snowpack or set a substrate."
+                      " If wanted, add a transparent substrate to supress this warning" % optical_depth)
 
         x = scipy.linalg.solve_banded((nband, nband), bBC, b, overwrite_ab=True, overwrite_b=True)
 

smrt/rtsolver/nadir_lrm_altimetry.py

@@ -26,9 +26,9 @@ class NadirLRMAltimetry(object):
     backscatter of the interface, but are similar in the way the waveform is calculated, which concerns the solver here.
 
     :param oversampling: integer number defining the number of subgates used for the computation in each altimeter gate.
-    This is equivalent to multiply the bandwidth by this number. It is used to perform more accurate computation.
-    :param return_oversampled: by default the backscatter is returned for each gate. If set to True, the oversampled waveform is returned instead.
-    See the 'oversampling' argument.
+        This is equivalent to multiply the bandwidth by this number. It is used to perform more accurate computation.
+    :param return_oversampled: by default the backscatter is returned for each gate. If set to True, the oversampled waveform 
+        is returned instead. See the 'oversampling' argument.
     :param return_contributions: return volume, surface and interface backscatter contributions in addition to the total backscatter.
     """
 
@@ -56,11 +56,11 @@ def __init__(self, waveform_model=None, oversampling=10, return_oversampled=Fals
         if self.skip_pfs_convolution and self.theta_inc_sampling > 1:
             if not self.return_theta_inc_sampling:
                 smrt_warn("When skip_pfs_convolution is True and theta_inc_sampling > 1, it does not make sense to not return_theta_inc_sampling."
-                     "To prevent this warning, explicitly set return_theta_inc_sampling = True.")
+                          "To prevent this warning, explicitly set return_theta_inc_sampling = True.")
                 self.return_theta_inc_sampling = True
         if self.return_theta_inc_sampling and self.theta_inc_sampling <= 1:
             smrt_warn("It does not make sense to return_theta_inc_sampling if theta_inc_sampling is <= 1."
-                 "To prevent this warning, explicitly set return_theta_inc_sampling = True.")
+                      "To prevent this warning, explicitly set return_theta_inc_sampling = True.")
             self.return_theta_inc_sampling = False
 
     def solve(self, snowpack, emmodels, sensor, atmosphere=None):