misc: cleanup docstrings and typos

devito/finite_differences/derivative.py

@@ -337,8 +337,6 @@ def _eval_at(self, func):
         """
         # If an x0 already exists do not overwrite it
         x0 = self.x0 or dict(func.indices_ref._getters)
-        # expr_x0 = self.expr.indices_ref._getters
-        # x0 = {k: v for k, v in x0.items() if k in self.dims and expr_x0[k] is not v}
         if self.expr.is_Add:
             # If `expr` has both staggered and non-staggered terms such as
             # `(u(x + h_x/2) + v(x)).dx` then we exploit linearity of FD to split

devito/finite_differences/differentiable.py

@@ -330,7 +330,8 @@ def div(self, shift=None, order=None, method='FD'):
             Discretization order for the finite differences.
             Uses `func.space_order` when not specified
         method: str, optional, default='FD'
-            Discretization method. Options are 'FD' (default) and 'RSFD'
+            Discretization method. Options are 'FD' (default) and
+            'RSFD' (rotated staggered grid finite-difference).
         """
         space_dims = [d for d in self.dimensions if d.is_Space]
         shift_x0 = make_shift_x0(shift, (len(space_dims),))
@@ -353,7 +354,8 @@ def grad(self, shift=None, order=None, method='FD'):
             Discretization order for the finite differences.
             Uses `func.space_order` when not specified
         method: str, optional, default='FD'
-            Discretization method. Options are 'FD' (default) and 'RSFD'
+            Discretization method. Options are 'FD' (default) and
+            'RSFD' (rotated staggered grid finite-difference).
         """
         from devito.types.tensor import VectorFunction, VectorTimeFunction
         space_dims = [d for d in self.dimensions if d.is_Space]

devito/finite_differences/finite_difference.py

@@ -25,22 +25,22 @@ def first_derivative(expr, dim, fd_order=None, side=centered, matvec=direct, x0=
         Expression for which the first-order derivative is produced.
     dim : Dimension
         The Dimension w.r.t. which to differentiate.
-    fd_order : int, optional
+    fd_order : int, optional, default=expr.space_order
         Coefficient discretization order. Note: this impacts the width of
-        the resulting stencil. Defaults to `expr.space_order`.
-    side : Side, optional
+        the resulting stencil.
+    side : 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`.
-    matvec : Transpose, optional
+        or right (at x +1).
+    matvec : Transpose, optional, default=direct
         Forward (matvec=direct) or transpose (matvec=transpose) mode of the
-        finite difference. Defaults to `direct`.
-    x0 : dict, optional
+        finite difference.
+    x0 : dict, optional, default=None
         Origin of the finite-difference scheme as a map dim: origin_dim.
-    coefficients : string, optional
-        Use taylor or custom coefficients (weights). Defaults to taylor.
-    expand : bool, optional
+    coefficients : string, optional, default='taylor'
+        Use taylor or custom coefficients (weights).
+    expand : bool, optional, default=True
         If True, the derivative is fully expanded as a sum of products,
-        otherwise an IndexSum is returned. Defaults to True.
+        otherwise an IndexSum is returned.
 
     Returns
     -------
@@ -87,7 +87,7 @@ def first_derivative(expr, dim, fd_order=None, side=centered, matvec=direct, x0=
     fd_order = fd_order or expr.space_order
     deriv_order = 1
 
-    # Enforce sable time coefficients
+    # Enforce stable time coefficients
     if dim.is_Time and coefficients != 'symbolic':
         coefficients = 'taylor'
 
@@ -107,21 +107,22 @@ def cross_derivative(expr, dims, fd_order, deriv_order, x0=None, **kwargs):
         Expression for which the cross derivative is produced.
     dims : tuple of Dimension
         Dimensions w.r.t. which to differentiate.
-    fd_order : tuple of ints
+    fd_order : int, optional, default=expr.space_order
         Coefficient discretization order. Note: this impacts the width of
         the resulting stencil.
-    deriv_order : tuple of ints
-        Derivative order, e.g. 2 for a second-order derivative.
-    matvec : Transpose, optional
+    side : Side, optional, default=centered
+        Side of the finite difference location, centered (at x), left (at x - 1)
+        or right (at x +1).
+    matvec : Transpose, optional, default=direct
         Forward (matvec=direct) or transpose (matvec=transpose) mode of the
-        finite difference. Defaults to `direct`.
-    x0 : dict, optional
+        finite difference.
+    x0 : dict, optional, default=None
         Origin of the finite-difference scheme as a map dim: origin_dim.
-    coefficients : string, optional
-        Use taylor or custom coefficients (weights). Defaults to taylor.
-    expand : bool, optional
+    coefficients : string, optional, default='taylor'
+        Use taylor or custom coefficients (weights).
+    expand : bool, optional, default=True
         If True, the derivative is fully expanded as a sum of products,
-        otherwise an IndexSum is returned. Defaults to True.
+        otherwise an IndexSum is returned.
 
     Returns
     -------
@@ -179,21 +180,22 @@ def generic_derivative(expr, dim, fd_order, deriv_order, matvec=direct, x0=None,
         Expression for which the derivative is produced.
     dim : Dimension
         The Dimension w.r.t. which to differentiate.
-    fd_order : int
+    fd_order : int, optional, default=expr.space_order
         Coefficient discretization order. Note: this impacts the width of
         the resulting stencil.
-    deriv_order : int
-        Derivative order, e.g. 2 for a second-order derivative.
-    matvec : Transpose, optional
+    side : Side, optional, default=centered
+        Side of the finite difference location, centered (at x), left (at x - 1)
+        or right (at x +1).
+    matvec : Transpose, optional, default=direct
         Forward (matvec=direct) or transpose (matvec=transpose) mode of the
-        finite difference. Defaults to `direct`.
-    x0 : dict, optional
+        finite difference.
+    x0 : dict, optional, default=None
         Origin of the finite-difference scheme as a map dim: origin_dim.
-    coefficients : string, optional
-        Use taylor or custom coefficients (weights). Defaults to taylor.
-    expand : bool, optional
+    coefficients : string, optional, default='taylor'
+        Use taylor or custom coefficients (weights).
+    expand : bool, optional, default=True
         If True, the derivative is fully expanded as a sum of products,
-        otherwise an IndexSum is returned. Defaults to True.
+        otherwise an IndexSum is returned.
 
     Returns
     -------

devito/finite_differences/operators.py

@@ -12,17 +12,18 @@ def div(func, shift=None, order=None, method='FD'):
         Discretization order for the finite differences.
         Uses `func.space_order` when not specified
     method: str, optional, default='FD'
-        Discretization method. Options are 'FD' (default) and 'RSFD'
+        Discretization method. Options are 'FD' (default) and
+        'RSFD' (rotated staggered grid finite-difference).
     """
     try:
         return func.div(shift=shift, order=order, method=method)
     except AttributeError:
         return 0
 
 
-def div45(func, shift=None, order=None, method='FD'):
+def div45(func, shift=None, order=None):
     """
-    Divergence of the input Function, using the 45 degrees rotated derivative.
+    Divergence of the input Function, using 45 degrees rotated derivative.
 
     Parameters
     ----------
@@ -34,10 +35,7 @@ def div45(func, shift=None, order=None, method='FD'):
         Discretization order for the finite differences.
         Uses `func.space_order` when not specified
     """
-    try:
-        return func.div(shift=shift, order=order, method='RSFD')
-    except AttributeError:
-        return 0
+    return div(func, shift=shift, order=order, method='RSFD')
 
 
 def grad(func, shift=None, order=None, method='FD'):
@@ -54,7 +52,8 @@ def grad(func, shift=None, order=None, method='FD'):
         Discretization order for the finite differences.
         Uses `func.space_order` when not specified
     method: str, optional, default='FD'
-        Discretization method. Options are 'FD' (default) and 'RSFD'
+        Discretization method. Options are 'FD' (default) and
+        'RSFD' (rotated staggered grid finite-difference).
     """
     try:
         return func.grad(shift=shift, order=order, method=method)
@@ -64,7 +63,7 @@ def grad(func, shift=None, order=None, method='FD'):
 
 def grad45(func, shift=None, order=None):
     """
-    Gradient of the input Function, using the 45 degrees rotated derivative.
+    Gradient of the input Function, using 45 degrees rotated derivative.
 
     Parameters
     ----------
@@ -76,10 +75,7 @@ def grad45(func, shift=None, order=None):
         Discretization order for the finite differences.
         Uses `func.space_order` when not specified
     """
-    try:
-        return func.grad(shift=shift, order=order, method='RSFD')
-    except AttributeError:
-        raise AttributeError("Gradient not supported for class %s" % func.__class__)
+    return grad(func, shift=shift, order=order, method='RSFD')
 
 
 def curl(func, shift=None, order=None, method='FD'):
@@ -96,7 +92,8 @@ def curl(func, shift=None, order=None, method='FD'):
         Discretization order for the finite differences.
         Uses `func.space_order` when not specified
     method: str, optional, default='FD'
-        Discretization method. Options are 'FD' (default) and 'RSFD'
+        Discretization method. Options are 'FD' (default) and
+        'RSFD' (rotated staggered grid finite-difference).
     """
     try:
         return func.curl(shift=shift, order=order, method=method)
@@ -106,7 +103,7 @@ def curl(func, shift=None, order=None, method='FD'):
 
 def curl45(func, shift=None, order=None):
     """
-    Curl of the input Function, using the 45 degrees rotated derivative.
+    Curl of the input Function, using 45 degrees rotated derivative.
     Only supported for VectorFunction
 
     Parameters
@@ -119,10 +116,7 @@ def curl45(func, shift=None, order=None):
         Discretization order for the finite differences.
         Uses `func.space_order` when not specified
     """
-    try:
-        return func.curl(shift=shift, order=order, method='RSFD')
-    except AttributeError:
-        raise AttributeError("Curl only supported for 3D VectorFunction")
+    return curl(func, shift=shift, order=order, method='RSFD')
 
 
 def laplace(func, shift=None, order=None, method='FD'):

devito/finite_differences/tools.py

@@ -246,7 +246,8 @@ def numeric_weights(function, deriv_order, indices, x0):
     return finite_diff_weights(deriv_order, indices, x0)[-1][-1]
 
 
-fd_weights_registry = {'taylor': numeric_weights, 'symbolic': symbolic_weights}
+fd_weights_registry = {'taylor': numeric_weights, 'standard': numeric_weights,
+                       'symbolic': symbolic_weights}
 
 
 def generate_indices(expr, dim, order, side=None, matvec=None, x0=None):
@@ -375,9 +376,13 @@ def generate_indices_staggered(expr, dim, order, side=None, x0=None):
             indices = IndexSet(dim, indices)
         else:
             if x0 is None or order % 2 == 0:
+                # No _eval_at or even order derivatives
+                # keep the centered indices
                 o_min = -order//2
                 o_max = order//2
             elif start is dim:
+                # Staggered FD requires half cell shift
+                # for stability
                 o_min = -order//2 + 1
                 o_max = order//2
                 start = dim + diff/2

devito/types/dense.py

@@ -2,7 +2,6 @@
 from ctypes import POINTER, Structure, c_int, c_ulong, c_void_p, cast, byref
 from functools import wraps, reduce
 from operator import mul
-import warnings
 
 import numpy as np
 import sympy
@@ -74,14 +73,8 @@ def __init_finalize__(self, *args, function=None, **kwargs):
         # Symbolic (finite difference) coefficients
         self._coefficients = kwargs.get('coefficients', self._default_fd)
         if self._coefficients not in fd_weights_registry:
-            if self._coefficients == 'standard':
-                self._coefficients = 'taylor'
-                warnings.warn("The `standard` mode is deprecated and will be removed in "
-                              "future versions of Devito, use `taylor` instead",
-                              category=DeprecationWarning, stacklevel=2)
-            else:
-                raise ValueError("coefficients must be `taylor` or `symbolic`"
-                                 " not %s" % self._coefficients)
+            raise ValueError("coefficients must be one of %s"
+                             " not %s" % (str(fd_weights_registry), self._coefficients))
 
         # Data-related properties
         self._data = None

devito/types/tensor.py

@@ -200,7 +200,8 @@ def div(self, shift=None, order=None, method='FD'):
             Discretization order for the finite differences.
             Uses `func.space_order` when not specified
         method: str, optional, default='FD'
-            Discretization method. Options are 'FD' (default) and 'RSFD'
+            Discretization method. Options are 'FD' (default) and
+            'RSFD' (rotated staggered grid finite-difference).
         """
         comps = []
         func = vec_func(self)
@@ -327,7 +328,8 @@ def div(self, shift=None, order=None, method='FD'):
             Discretization order for the finite differences.
             Uses `func.space_order` when not specified
         method: str, optional, default='FD'
-            Discretization method. Options are 'FD' (default) and 'RSFD'
+            Discretization method. Options are 'FD' (default) and
+            'RSFD' (rotated staggered grid finite-difference).
         """
         shift_x0 = make_shift_x0(shift, (len(self.space_dimensions),))
         order = order or self.space_order
@@ -375,7 +377,8 @@ def curl(self, shift=None, order=None, method='FD'):
             Discretization order for the finite differences.
             Uses `func.space_order` when not specified
         method: str, optional, default='FD'
-            Discretization method. Options are 'FD' (default) and 'RSFD'
+            Discretization method. Options are 'FD' (default) and
+            'RSFD' (rotated staggered grid finite-difference).
         """
         if len(self.space_dimensions) != 3:
             raise AttributeError("Curl only supported for 3D VectorFunction")
@@ -411,7 +414,8 @@ def grad(self, shift=None, order=None, method='FD'):
             Discretization order for the finite differences.
             Uses `func.space_order` when not specified
         method: str, optional, default='FD'
-            Discretization method. Options are 'FD' (default) and 'RSFD'
+            Discretization method. Options are 'FD' (default) and
+            'RSFD' (rotated staggered grid finite-difference).
         """
         func = tens_func(self)
         ndim = len(self.space_dimensions)