Merge pull request #2223 from ZoeLeibowitz/docstrings

misc: Docstring updates

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

@@ -168,10 +168,10 @@ 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
-        If True, JIT compile using a C++ compiler. Defaults to False.
-    mpi : bool, optional
-        If True, JIT compile using an MPI compiler. Defaults to False.
+    cpp : bool, optional, default=False
+        If True, JIT compile using a C++ compiler.
+    mpi : bool, optional, default=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

@@ -25,18 +25,18 @@ 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
-        Derivative order. Defaults to 1.
-    side : Side or tuple of Side, optional
+        the resulting stencil.
+    deriv_order: int or tuple of int, optional, default=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``.
-    transpose : Transpose, optional
+        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

@@ -18,9 +18,8 @@ class Constant(DataSymbol, ArgProvider):
     ----------
     name : str
         Name of the symbol.
-    dtype : data-type, optional
-        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.
 
     Examples
     --------

devito/types/dense.py

@@ -889,8 +889,8 @@ 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
-        Discretisation order for space derivatives. Defaults to 1.
+    space_order : int or 3-tuple of ints, optional, default=1
+        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
@@ -910,12 +910,11 @@ class Function(DiscreteFunction):
     dimensions : tuple of Dimension, optional
         Dimensions associated with the object. Only necessary if `grid` isn't
         given.
-    dtype : data-type, optional
-        Any object that can be interpreted as a numpy data type. Defaults
-        to `np.float32`.
-    staggered : Dimension or tuple of Dimension or Stagger, optional
+    dtype : data-type, optional, default=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, 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
@@ -1220,8 +1219,8 @@ 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
-        Discretisation order for space derivatives. Defaults to 1.
+    space_order : int or 3-tuple of ints, optional, default=1
+        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
@@ -1243,10 +1242,9 @@ class TimeFunction(Function):
     dimensions : tuple of Dimension, optional
         Dimensions associated with the object. Only necessary if `grid` isn't
         given.
-    dtype : data-type, optional
-        Any object that can be interpreted as a numpy data type. Defaults
-        to `np.float32`.
-    save : int or Buffer, optional
+    dtype : data-type, optional, default=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 `u(t, x)` has shape (3, 100), then, in an Operator,
@@ -1258,11 +1256,11 @@ class TimeFunction(Function):
         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
-        TimeDimension to be used in the TimeFunction. Defaults to `grid.time_dim`.
-    staggered : Dimension or tuple of Dimension or Stagger, optional
+    time_dim : Dimension, optional, default=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, 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

@@ -50,7 +50,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
@@ -774,19 +774,19 @@ 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.
+        indirectly via the ``condition`` expression.
 
     Examples
     --------

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
-        The right-hand side. Defaults to 0.
-    subdomain : SubDomain, optional
+    rhs : expr-like, optional, default=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.
-    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/grid.py

@@ -68,21 +68,18 @@ class Grid(CartesianDiscretization, ArgProvider):
     ----------
     shape : tuple of ints
         Shape of the computational domain in grid points.
-    extent : tuple of floats, optional
-        Physical extent of the domain in m; defaults to a unit box of extent 1m
-        in all dimensions.
-    origin : tuple of floats, optional
-        Physical coordinate of the origin of the domain; defaults to 0.0 in all
-        dimensions.
+    extent : tuple of floats, default=unit box of extent 1m in all dimensions
+        Physical extent of the domain in m.
+    origin : tuple of floats, default=0.0 in all dimensions
+        Physical coordinate of the origin of the domain.
     dimensions : tuple of SpaceDimension, optional
         The dimensions of the computational domain encapsulated by this Grid.
     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

@@ -734,17 +734,16 @@ 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
-        Discretisation order for space derivatives. Defaults to 0.
-    shape : tuple of ints, optional
-        Shape of the object. Defaults to ``(npoint,)``.
+    space_order : int, optional, default=0
+        Discretisation order for space derivatives.
+    shape : tuple of ints, optional, default=(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
-        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
+    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
         Controller for memory allocation. To be used, for example, when one wants
@@ -853,19 +852,18 @@ 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
-        Discretisation order for space derivatives. Defaults to 0.
-    time_order : int, optional
-        Discretisation order for time derivatives. Defaults to 1.
-    shape : tuple of ints, optional
-        Shape of the object. Defaults to ``(nt, npoint)``.
+    space_order : int, optional, default=0
+        Discretisation order for space derivatives.
+    time_order : int, optional, default=1
+        Discretisation order for time derivatives.
+    shape : tuple of ints, optional, default=(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
-        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
+    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
         Controller for memory allocation. To be used, for example, when one wants
@@ -1003,16 +1001,15 @@ 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
-        Discretisation order for space derivatives. Defaults to 0.
-    shape : tuple of ints, optional
-        Shape of the object. Defaults to `(npoint,)`.
+    space_order : int, optional, default=0
+        Discretisation order for space derivatives.
+    shape : tuple of ints, optional, default=(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
-        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
@@ -1168,19 +1165,18 @@ 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
-        Discretisation order for space derivatives. Defaults to 0.
-    time_order : int, optional
-        Discretisation order for time derivatives. Default to 1.
-    shape : tuple of ints, optional
-        Shape of the object. Defaults to `(npoint,)`.
+    space_order : int, optional, default=0
+        Discretisation order for space derivatives.
+    time_order : int, optional, default=1
+        Discretisation order for time derivatives.
+    shape : tuple of ints, optional, default=(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
-        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
+    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
         Controller for memory allocation. To be used, for example, when one wants

devito/types/tensor.py

@@ -29,8 +29,8 @@ 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
-        Discretisation order for space derivatives. Defaults to 1. ``space_order`` also
+    space_order : int or 3-tuple of ints, optional, default=1
+        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
@@ -42,11 +42,11 @@ 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
-        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.
     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
@@ -56,13 +56,10 @@ class TensorFunction(AbstractTensor):
     padding : int or tuple of ints, optional
         Allocate extra grid points to maximize data access alignment. When a tuple
         of ints, one int per Dimension should be provided.
-    symmetric : bool, optional
-        Whether the tensor is symmetric or not. Defaults to True.
-    diagonal : Bool, optional
-        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.
+    symmetric : bool, optional, default=True
+        Whether the tensor is symmetric or not.
+    diagonal : Bool, optional, default=False
+        Whether the tensor is diagonal or not.
     """
 
     _is_TimeDependent = False