misc: Docstring updates

devito/arch/compiler.py

@@ -163,9 +163,9 @@ def __init__(self):
     suffix : str, optional
         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
+    cpp : bool, optional, default=False
         If True, JIT compile using a C++ compiler. Defaults to False.
-    mpi : bool, optional
+    mpi : bool, optional, default=False
         If True, JIT compile using an MPI compiler. Defaults to False.
     platform : Platform, optional
         The target Platform on which the JIT compiler will be used.

devito/finite_differences/derivative.py

@@ -25,16 +25,16 @@ class Derivative(sympy.Derivative, Differentiable):
     expr : expr-like
         Expression for which the Derivative is produced.
     dims : Dimension or tuple of Dimension
-        Dimenions w.r.t. which to differentiate.
-    fd_order : int or tuple of int, optional
+        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.
-    deriv_order: int or tuple of int, optional
+    deriv_order: int or tuple of int, optional, default=1
         Derivative order. Defaults to 1.
-    side : Side or tuple of Side, optional
+    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``.
-    transpose : Transpose, optional
+    transpose : Transpose, optional, default=direct
         Forward (matvec=direct) or transpose (matvec=transpose) mode of the
         finite difference. Defaults to ``direct``.
     subs : dict, optional

devito/types/constant.py

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

devito/types/dense.py

@@ -899,7 +899,7 @@ class Function(DiscreteFunction):
         Carries shape, dimensions, and dtype of the Function. When grid is not
         provided, shape and dimensions must be given. For MPI execution, a
         Grid is compulsory.
-    space_order : int or 3-tuple of ints, optional
+    space_order : int or 3-tuple of ints, optional, default=1
         Discretisation order for space derivatives. Defaults to 1. ``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
@@ -912,12 +912,12 @@ class Function(DiscreteFunction):
         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
+    dtype : data-type, optional, default=np.float32
         Any object that can be interpreted as a numpy data type. Defaults
         to ``np.float32``.
-    staggered : Dimension or tuple of Dimension or Stagger, optional
+    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, optional
+    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
         Controller for memory allocation. To be used, for example, when one wants
@@ -1215,7 +1215,7 @@ class TimeFunction(Function):
         Carries shape, dimensions, and dtype of the Function. When grid is not
         provided, shape and dimensions must be given. For MPI execution, a
         Grid is compulsory.
-    space_order : int or 3-tuple of ints, optional
+    space_order : int or 3-tuple of ints, optional, default=1
         Discretisation order for space derivatives. Defaults to 1. ``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
@@ -1224,16 +1224,16 @@ class TimeFunction(Function):
         an integer, one can pass a 3-tuple ``(o, lp, rp)`` indicating the discretization
         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
+    time_order : int, optional, default=1
         Discretization order for time derivatives. Defaults to 1.
     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
+    dtype : data-type, optional, default=np.float32
         Any object that can be interpreted as a numpy data type. Defaults
         to `np.float32`.
-    save : int or Buffer, optional
+    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
         ``u(t, x)`` has shape (3, 100), then, in an Operator, ``t`` will assume the
@@ -1244,11 +1244,11 @@ class TimeFunction(Function):
         Alternatively, if all of the intermediate results are required (or, simply, to
         avoid using an alternating buffer), an explicit value for ``save`` ( an integer)
         must be provided.
-    time_dim : Dimension, optional
+    time_dim : Dimension, optional, default=grid.time_dim
         TimeDimension to be used in the TimeFunction. Defaults to ``grid.time_dim``.
-    staggered : Dimension or tuple of Dimension or Stagger, optional
+    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, optional
+    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
         Controller for memory allocation. To be used, for example, when one wants

devito/types/dimension.py

@@ -48,7 +48,7 @@ class Dimension(ArgProvider):
     ----------
     name : str
         Name of the dimension.
-    spacing : symbol, optional
+    spacing : symbol, optional, default=h_name
         A symbol to represent the physical spacing along this Dimension.
 
     Examples
@@ -755,16 +755,16 @@ class ConditionalDimension(DerivedDimension):
     ----------
     name : str
         Name of the dimension.
-    parent : Dimension, optional
+    parent : Dimension
         The parent Dimension.
-    factor : int, optional
+    factor : int, optional, default=None
         The number of iterations between two executions of the if-branch. If None
         (default), ``condition`` must be provided.
-    condition : expr-like, optional
+    condition : expr-like, optional, default=None
         An arbitrary SymPy expression, typically involving the ``parent``
         Dimension. When it evaluates to True, the if-branch is executed. If None
         (default), ``factor`` must be provided.
-    indirect : bool, optional
+    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.

devito/types/equation.py

@@ -25,15 +25,15 @@ class Eq(sympy.Eq, Evaluable):
     ----------
     lhs : Function or SparseFunction
         The left-hand side.
-    rhs : expr-like, optional
+    rhs : expr-like, optional, default=0
         The right-hand side. Defaults to 0.
-    subdomain : SubDomain, optional
+    subdomain : SubDomain, optional, default=None
         To restrict the computation of the Eq to a particular sub-region in the
         computational domain.
-    coefficients : Substitutions, optional
+    coefficients : Substitutions, optional, default=None
         Can be used to replace symbolic finite difference weights with user
         defined weights.
-    implicit_dims : Dimension or list of Dimension, optional
+    implicit_dims : Dimension or list of Dimension, optional, default=None
         An ordered list of Dimensions that do not explicitly appear in either the
         left-hand side or in the right-hand side, but that should be honored when
         constructing an Operator.

devito/types/sparse.py

@@ -717,17 +717,17 @@ class SparseFunction(AbstractSparseFunction):
         The computational domain from which the sparse points are sampled.
     coordinates : np.ndarray, optional
         The coordinates of each sparse point.
-    space_order : int, optional
+    space_order : int, optional, default=0
         Discretisation order for space derivatives. Defaults to 0.
-    shape : tuple of ints, optional
+    shape : tuple of ints, optional, default=(npoint,)
         Shape of the object. Defaults to ``(npoint,)``.
     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 : data-type, optional, default=np.float32
         Any object that can be interpreted as a numpy data type. Defaults
         to ``np.float32``.
-    initializer : callable or any object exposing the buffer interface, optional
+    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
         Controller for memory allocation. To be used, for example, when one wants
@@ -836,19 +836,19 @@ class SparseTimeFunction(AbstractSparseTimeFunction, SparseFunction):
         The computational domain from which the sparse points are sampled.
     coordinates : np.ndarray, optional
         The coordinates of each sparse point.
-    space_order : int, optional
+    space_order : int, optional, default=0
         Discretisation order for space derivatives. Defaults to 0.
-    time_order : int, optional
+    time_order : int, optional, default=1
         Discretisation order for time derivatives. Defaults to 1.
-    shape : tuple of ints, optional
+    shape : tuple of ints, optional, default=(nt, npoint)
         Shape of the object. Defaults to ``(nt, npoint)``.
     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 : data-type, optional, default=np.float32
         Any object that can be interpreted as a numpy data type. Defaults
         to ``np.float32``.
-    initializer : callable or any object exposing the buffer interface, optional
+    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
         Controller for memory allocation. To be used, for example, when one wants
@@ -985,14 +985,14 @@ class PrecomputedSparseFunction(AbstractSparseFunction):
         So for `r=6`, we will store 18 coefficients per sparse point (instead of
         potentially 216).  Must be a three-dimensional array of shape
         `(npoint, grid.ndim, r)`.
-    space_order : int, optional
+    space_order : int, optional, default=0
         Discretisation order for space derivatives. Defaults to 0.
-    shape : tuple of ints, optional
+    shape : tuple of ints, optional, default=(npoint,)
         Shape of the object. Defaults to `(npoint,)`.
     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 : data-type, optional, dtype=np.float32
         Any object that can be interpreted as a numpy data type. Defaults
         to `np.float32`.
     initializer : callable or any object exposing the buffer interface, optional
@@ -1148,19 +1148,19 @@ class PrecomputedSparseTimeFunction(AbstractSparseTimeFunction,
         So for `r=6`, we will store 18 coefficients per sparse point (instead of
         potentially 216).  Must be a three-dimensional array of shape
         `(npoint, grid.ndim, r)`.
-    space_order : int, optional
+    space_order : int, optional, default=0
         Discretisation order for space derivatives. Defaults to 0.
-    time_order : int, optional
+    time_order : int, optional, default=1
         Discretisation order for time derivatives. Default to 1.
-    shape : tuple of ints, optional
+    shape : tuple of ints, optional, default=(npoint,)
         Shape of the object. Defaults to `(npoint,)`.
     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 : data-type, optional, dtype=np.float32
         Any object that can be interpreted as a numpy data type. Defaults
         to `np.float32`.
-    initializer : callable or any object exposing the buffer interface, optional
+    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
         Controller for memory allocation. To be used, for example, when one wants

devito/types/tensor.py

@@ -29,7 +29,7 @@ class TensorFunction(AbstractTensor):
         Carries shape, dimensions, and dtype of the TensorFunction. When grid is not
         provided, shape and dimensions must be given. For MPI execution, a
         Grid is compulsory.
-    space_order : int or 3-tuple of ints, optional
+    space_order : int or 3-tuple of ints, optional, default=1
         Discretisation order for space derivatives. Defaults to 1. ``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
@@ -42,7 +42,7 @@ class TensorFunction(AbstractTensor):
         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
+    dtype : data-type, optional, default=np.float32
         Any object that can be interpreted as a numpy data type. Defaults
         to ``np.float32``.
     staggered : Dimension or tuple of Dimension or Stagger, optional
@@ -57,9 +57,9 @@ class TensorFunction(AbstractTensor):
         .. deprecated:: shouldn't be used; padding is now automatically inserted.
         Allocate extra grid points to maximize data access alignment. When a tuple
         of ints, one int per Dimension should be provided.
-    symmetric : bool, optional
+    symmetric : bool, optional, default=True
         Whether the tensor is symmetric or not. Defaults to True.
-    diagonal : Bool, optional
+    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