misc: Edit docstrings and README

README.md

@@ -47,7 +47,7 @@ example above being for a single equation). This code may also be compiled and
 executed
 
 ```python
->>> op(t=timesteps)
+>>> op(t=timesteps, dt=dt)
 ```
 
 There is virtually no limit to the complexity of an `Operator` -- the Devito

devito/arch/compiler.py

@@ -164,9 +164,9 @@ def __init__(self):
         The JIT compiler version to be used. For example, assuming ``CC=gcc`` and
         ``suffix='4.9'``, the ``gcc-4.9`` will be used as JIT compiler.
     cpp : bool, optional, default=False
-        If True, JIT compile using a C++ compiler. Defaults to False.
+        If True, JIT compile using a C++ compiler.
     mpi : bool, optional, default=False
-        If True, JIT compile using an MPI compiler. Defaults to False.
+        If True, JIT compile using an MPI compiler.
     platform : Platform, optional
         The target Platform on which the JIT compiler will be used.
     """

devito/builtins/arithmetic.py

@@ -31,8 +31,8 @@ def norm(f, order=2):
     ----------
     f : Function
         Input Function.
-    order : int, optional
-        The order of the norm. Defaults to 2.
+    order : int, default=2
+        The order of the norm.
     """
     Pow = dv.finite_differences.differentiable.Pow
     kwargs = {}

devito/finite_differences/derivative.py

@@ -28,15 +28,15 @@ class Derivative(sympy.Derivative, Differentiable):
         Dimensions w.r.t. which to differentiate.
     fd_order : int or tuple of int, optional, default=1
         Coefficient discretization order. Note: this impacts the width of
-        the resulting stencil. Defaults to 1.
+        the resulting stencil.
     deriv_order: int or tuple of int, optional, default=1
-        Derivative order. Defaults to 1.
+        Derivative order.
     side : Side or tuple of Side, optional, default=centered
         Side of the finite difference location, centered (at x), left (at x - 1)
-        or right (at x +1). Defaults to ``centered``.
+        or right (at x +1).
     transpose : Transpose, optional, default=direct
         Forward (matvec=direct) or transpose (matvec=transpose) mode of the
-        finite difference. Defaults to ``direct``.
+        finite difference.
     subs : dict, optional
         Substitutions to apply to the finite-difference expression after evaluation.
     x0 : dict, optional

devito/types/constant.py

@@ -19,8 +19,7 @@ class Constant(DataSymbol, ArgProvider):
     name : str
         Name of the symbol.
     dtype : data-type, optional, default=np.float32
-        Any object that can be interpreted as a numpy data type. Defaults
-        to ``np.float32``.
+        Any object that can be interpreted as a numpy data type.
 
     Examples
     --------

devito/types/dense.py

@@ -892,7 +892,7 @@ class Function(DiscreteFunction):
         provided, shape and dimensions must be given. For MPI execution, a
         Grid is compulsory.
     space_order : int or 3-tuple of ints, optional, default=1
-        Discretisation order for space derivatives. Defaults to 1. ``space_order`` also
+        Discretisation order for space derivatives. ``space_order`` also
         impacts the number of points available around a generic point of interest.  By
         default, ``space_order`` points are available on both sides of a generic point of
         interest, including those nearby the grid boundary. Sometimes, fewer points
@@ -905,8 +905,7 @@ class Function(DiscreteFunction):
     dimensions : tuple of Dimension, optional
         Dimensions associated with the object. Only necessary if ``grid`` isn't given.
     dtype : data-type, optional, default=np.float32
-        Any object that can be interpreted as a numpy data type. Defaults
-        to ``np.float32``.
+        Any object that can be interpreted as a numpy data type.
     staggered : Dimension or tuple of Dimension or Stagger, optional, default=None
         Define how the Function is staggered.
     initializer : callable or any object exposing the buffer interface, default=None
@@ -1216,7 +1215,7 @@ class TimeFunction(Function):
         provided, shape and dimensions must be given. For MPI execution, a
         Grid is compulsory.
     space_order : int or 3-tuple of ints, optional, default=1
-        Discretisation order for space derivatives. Defaults to 1. ``space_order`` also
+        Discretisation order for space derivatives. ``space_order`` also
         impacts the number of points available around a generic point of interest.  By
         default, ``space_order`` points are available on both sides of a generic point of
         interest, including those nearby the grid boundary. Sometimes, fewer points
@@ -1225,14 +1224,13 @@ class TimeFunction(Function):
         order (``o``) as well as the number of points on the left (``lp``) and right
         (``rp``) sides of a generic point of interest.
     time_order : int, optional, default=1
-        Discretization order for time derivatives. Defaults to 1.
+        Discretisation order for time derivatives.
     shape : tuple of ints, optional
         Shape of the domain region in grid points. Only necessary if `grid` isn't given.
     dimensions : tuple of Dimension, optional
         Dimensions associated with the object. Only necessary if `grid` isn't given.
     dtype : data-type, optional, default=np.float32
-        Any object that can be interpreted as a numpy data type. Defaults
-        to `np.float32`.
+        Any object that can be interpreted as a numpy data type.
     save : int or Buffer, optional, default=None
         By default, ``save=None``, which indicates the use of alternating buffers. This
         enables cyclic writes to the TimeFunction. For example, if the TimeFunction
@@ -1245,7 +1243,7 @@ class TimeFunction(Function):
         avoid using an alternating buffer), an explicit value for ``save`` ( an integer)
         must be provided.
     time_dim : Dimension, optional, default=grid.time_dim
-        TimeDimension to be used in the TimeFunction. Defaults to ``grid.time_dim``.
+        TimeDimension to be used in the TimeFunction.
     staggered : Dimension or tuple of Dimension or Stagger, optional, default=None
         Define how the Function is staggered.
     initializer : callable or any object exposing the buffer interface, default=None

devito/types/dimension.py

@@ -784,7 +784,7 @@ class ConditionalDimension(DerivedDimension):
     indirect : bool, optional, default=False
         If True, use `self`, rather than the parent Dimension, to
         index into arrays. A typical use case is when arrays are accessed
-        indirectly via the ``condition`` expression. Defaults to False.
+        indirectly via the ``condition`` expression.
 
     Examples
     --------

devito/types/equation.py

@@ -26,7 +26,7 @@ class Eq(sympy.Eq, Evaluable):
     lhs : Function or SparseFunction
         The left-hand side.
     rhs : expr-like, optional, default=0
-        The right-hand side. Defaults to 0.
+        The right-hand side.
     subdomain : SubDomain, optional, default=None
         To restrict the computation of the Eq to a particular sub-region in the
         computational domain.

devito/types/grid.py

@@ -79,10 +79,9 @@ class Grid(CartesianDiscretization, ArgProvider):
     time_dimension : TimeDimension, optional
         The dimension used to define time in a `TimeFunction` created from
         this Grid.
-    dtype : data-type, optional
+    dtype : data-type, default=np.float32
         Any object that can be interpreted as a numpy data type, used as default
         data type to be inherited by all Functions created from this Grid.
-        Defaults to ``np.float32``.
     subdomains : tuple of SubDomain, optional
         If no subdomains are specified, the Grid only defines the two default
         subdomains ``interior`` and ``domain``.

devito/types/sparse.py

@@ -718,15 +718,14 @@ class SparseFunction(AbstractSparseFunction):
     coordinates : np.ndarray, optional
         The coordinates of each sparse point.
     space_order : int, optional, default=0
-        Discretisation order for space derivatives. Defaults to 0.
+        Discretisation order for space derivatives.
     shape : tuple of ints, optional, default=(npoint,)
-        Shape of the object. Defaults to ``(npoint,)``.
+        Shape of the object.
     dimensions : tuple of Dimension, optional
         Dimensions associated with the object. Only necessary if the SparseFunction
         defines a multi-dimensional tensor.
     dtype : data-type, optional, default=np.float32
-        Any object that can be interpreted as a numpy data type. Defaults
-        to ``np.float32``.
+        Any object that can be interpreted as a numpy data type.
     initializer : callable or any object exposing the buffer interface, default=None
         Data initializer. If a callable is provided, data is allocated lazily.
     allocator : MemoryAllocator, optional
@@ -837,17 +836,16 @@ class SparseTimeFunction(AbstractSparseTimeFunction, SparseFunction):
     coordinates : np.ndarray, optional
         The coordinates of each sparse point.
     space_order : int, optional, default=0
-        Discretisation order for space derivatives. Defaults to 0.
+        Discretisation order for space derivatives.
     time_order : int, optional, default=1
-        Discretisation order for time derivatives. Defaults to 1.
+        Discretisation order for time derivatives.
     shape : tuple of ints, optional, default=(nt, npoint)
-        Shape of the object. Defaults to ``(nt, npoint)``.
+        Shape of the object.
     dimensions : tuple of Dimension, optional
         Dimensions associated with the object. Only necessary if the SparseFunction
         defines a multi-dimensional tensor.
     dtype : data-type, optional, default=np.float32
-        Any object that can be interpreted as a numpy data type. Defaults
-        to ``np.float32``.
+        Any object that can be interpreted as a numpy data type.
     initializer : callable or any object exposing the buffer interface, default=None
         Data initializer. If a callable is provided, data is allocated lazily.
     allocator : MemoryAllocator, optional
@@ -986,15 +984,14 @@ class PrecomputedSparseFunction(AbstractSparseFunction):
         potentially 216).  Must be a three-dimensional array of shape
         `(npoint, grid.ndim, r)`.
     space_order : int, optional, default=0
-        Discretisation order for space derivatives. Defaults to 0.
+        Discretisation order for space derivatives.
     shape : tuple of ints, optional, default=(npoint,)
-        Shape of the object. Defaults to `(npoint,)`.
+        Shape of the object.
     dimensions : tuple of Dimension, optional
         Dimensions associated with the object. Only necessary if the SparseFunction
         defines a multi-dimensional tensor.
-    dtype : data-type, optional, dtype=np.float32
-        Any object that can be interpreted as a numpy data type. Defaults
-        to `np.float32`.
+    dtype : data-type, optional, default=np.float32
+        Any object that can be interpreted as a numpy data type.
     initializer : callable or any object exposing the buffer interface, optional
         Data initializer. If a callable is provided, data is allocated lazily.
     allocator : MemoryAllocator, optional
@@ -1151,17 +1148,16 @@ class PrecomputedSparseTimeFunction(AbstractSparseTimeFunction,
         potentially 216).  Must be a three-dimensional array of shape
         `(npoint, grid.ndim, r)`.
     space_order : int, optional, default=0
-        Discretisation order for space derivatives. Defaults to 0.
+        Discretisation order for space derivatives.
     time_order : int, optional, default=1
-        Discretisation order for time derivatives. Default to 1.
+        Discretisation order for time derivatives.
     shape : tuple of ints, optional, default=(npoint,)
-        Shape of the object. Defaults to `(npoint,)`.
+        Shape of the object.
     dimensions : tuple of Dimension, optional
         Dimensions associated with the object. Only necessary if the SparseFunction
         defines a multi-dimensional tensor.
-    dtype : data-type, optional, dtype=np.float32
-        Any object that can be interpreted as a numpy data type. Defaults
-        to `np.float32`.
+    dtype : data-type, optional, default=np.float32
+        Any object that can be interpreted as a numpy data type.
     initializer : callable or any object exposing the buffer interface, default=None
         Data initializer. If a callable is provided, data is allocated lazily.
     allocator : MemoryAllocator, optional

devito/types/tensor.py

@@ -30,7 +30,7 @@ class TensorFunction(AbstractTensor):
         provided, shape and dimensions must be given. For MPI execution, a
         Grid is compulsory.
     space_order : int or 3-tuple of ints, optional, default=1
-        Discretisation order for space derivatives. Defaults to 1. ``space_order`` also
+        Discretisation order for space derivatives. ``space_order`` also
         impacts the number of points available around a generic point of interest.  By
         default, ``space_order`` points are available on both sides of a generic point of
         interest, including those nearby the grid boundary. Sometimes, fewer points
@@ -43,10 +43,10 @@ class TensorFunction(AbstractTensor):
     dimensions : tuple of Dimension, optional
         Dimensions associated with the object. Only necessary if ``grid`` isn't given.
     dtype : data-type, optional, default=np.float32
-        Any object that can be interpreted as a numpy data type. Defaults
-        to ``np.float32``.
+        Any object that can be interpreted as a numpy data type.
     staggered : Dimension or tuple of Dimension or Stagger, optional
-        Define how the TensorFunction is staggered.
+        Staggering of each component, needs to have the size of the tensor. Defaults
+        to the Dimensions.
     initializer : callable or any object exposing the buffer interface, optional
         Data initializer. If a callable is provided, data is allocated lazily.
     allocator : MemoryAllocator, optional
@@ -58,12 +58,9 @@ class TensorFunction(AbstractTensor):
         Allocate extra grid points to maximize data access alignment. When a tuple
         of ints, one int per Dimension should be provided.
     symmetric : bool, optional, default=True
-        Whether the tensor is symmetric or not. Defaults to True.
+        Whether the tensor is symmetric or not.
     diagonal : Bool, optional, default=False
-        Whether the tensor is diagonal or not. Defaults to False.
-    staggered: tuple of Dimension, optional
-        Staggering of each component, needs to have the size of the tensor. Defaults
-        to the Dimensions.
+        Whether the tensor is diagonal or not.
     """
 
     _is_TimeDependent = False