added more verbose explanations of solver, halo and g_factor (#433)

Co-authored-by: pawel <pawel.magnu@gmail.com>
Co-authored-by: Paweł Magnuszewski <47724273+pawelmagnu@users.noreply.github.com>

PyMPDATA/options.py

@@ -73,7 +73,13 @@ def dtype(self):
 
     @property
     def n_iters(self) -> int:
-        """number of iterations (1: upwind, 2: upwind + one corrective iteration, ...)"""
+        """Number of corrective iterations in the MPDATA algorithm + 1
+        e.g. (1: upwind, 2: upwind + one corrective iteration, ...).
+        Bigger values mean smaller error, but more computational cost.
+        It does not change the order of the method.
+        The order of the method depends on the variant of antidiffusive
+        velocity used, see for example `third_order_terms` option.
+        Note: not to confuse with n_steps in the Stepper."""
         return self._values["n_iters"]
 
     @property
@@ -86,7 +92,7 @@ def infinite_gauge(self) -> bool:
 
     @property
     def epsilon(self) -> float:
-        """value of constant used to prevent from divisins by zero
+        """value of constant used to prevent from divisions by zero
         in statements such as (a - b)/(a + b + eps)"""
         return self._values["epsilon"]
 
@@ -142,7 +148,13 @@ def __eq__(self, other):
 
     @property
     def n_halo(self) -> int:
-        """halo extent for a given options set"""
+        """Halo extent for a given options set.
+        The halo extent is the number of 'ghost layers' that need to be added
+        to the outside of the domain to ensure that the MPDATA stencil operations can be
+        applied to the edges of the domain.
+        It is similar to
+        [array padding](https://numpy.org/doc/stable/reference/generated/numpy.pad.html).
+        The halo extent is determined by the options set."""
         if self.divergent_flow or self.nonoscillatory or self.third_order_terms:
             return 2
         return 1

PyMPDATA/scalar_field.py

@@ -12,7 +12,7 @@
 
 
 class ScalarField(Field):
-    """n-dimensional scalar field including halo data"""
+    """n-dimensional scalar field including halo data, used to represent advectee, g_factor, etc."""
 
     def __init__(self, data: np.ndarray, halo: int, boundary_conditions: tuple):
         super().__init__(

PyMPDATA/solver.py

@@ -36,9 +36,14 @@ def call(self, flux, g_factor, step, iteration):  # pylint: disable=unused-argum
 
 
 class Solver:
-    """solution orchestrator requireing prior instantiation of: a `Stepper`,
-    a scalar advectee field, a vector advector field and optionally
-    a scala g_factor field"""
+    """Solution orchestrator requiring prior instantiation of: a `Stepper`,
+    a scalar advectee field (that which is advected),
+    a vector advector field (that which advects),
+    and optionally a scalar g_factor field (used in some cases of the advection equation).
+    Note: in some cases of advection, i.e. momentum advection,
+    the advectee can act upon the advector.
+    See `PyMPDATA_examples.Jarecka_et_al_2015` for an example of this.
+    """
 
     def __init__(
         self,
@@ -107,8 +112,14 @@ def advector(self) -> VectorField:
 
     @property
     def g_factor(self) -> ScalarField:
-        """g_factor field (with halo), unmodified by advance(),
-        assumed to be constant-in-time"""
+        """G_factor field (with halo), unmodified by advance(), assumed to be constant-in-time.
+        Can be used as a Jacobian for coordinate transformations,
+        e.g. into spherical coordinates.
+        For this type of usage, see
+        `PyMPDATA_examples.Williamson_and_Rasch_1989_as_in_Jaruga_et_al_2015_Fig_14`.
+        Can also be used to account for spatial variability of fluid density, see
+        `PyMPDATA_examples.Shipway_and_Hill_2012`.
+        e.g. the changing density of a fluid."""
         return self.__fields["g_factor"]
 
     def advance(

PyMPDATA/vector_field.py

@@ -20,7 +20,8 @@
 
 
 class VectorField(Field):
-    """n-component n-dimensional vector field including halo data"""
+    """n-component n-dimensional vector field including halo data,
+    used to represent the advector field"""
 
     def __init__(self, data: tuple, halo: int, boundary_conditions: tuple):
         super().__init__(