From 47be3e12e94ad1a1cb48c826ebd9ab344f303e81 Mon Sep 17 00:00:00 2001 From: mloubout Date: Mon, 11 Mar 2024 10:49:52 -0400 Subject: [PATCH] misc: cleanup docstrings and typos --- devito/finite_differences/derivative.py | 2 - devito/finite_differences/differentiable.py | 6 +- .../finite_differences/finite_difference.py | 66 ++++++++++--------- devito/finite_differences/operators.py | 32 ++++----- devito/finite_differences/tools.py | 7 +- devito/types/dense.py | 11 +--- devito/types/tensor.py | 12 ++-- 7 files changed, 67 insertions(+), 69 deletions(-) diff --git a/devito/finite_differences/derivative.py b/devito/finite_differences/derivative.py index 21dda75236..9e13454170 100644 --- a/devito/finite_differences/derivative.py +++ b/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 diff --git a/devito/finite_differences/differentiable.py b/devito/finite_differences/differentiable.py index d755e4c691..ee3e2ba38b 100644 --- a/devito/finite_differences/differentiable.py +++ b/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] diff --git a/devito/finite_differences/finite_difference.py b/devito/finite_differences/finite_difference.py index 718d024225..f0db5ad985 100644 --- a/devito/finite_differences/finite_difference.py +++ b/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 ------- diff --git a/devito/finite_differences/operators.py b/devito/finite_differences/operators.py index 2545dc049f..b664f1e9e1 100644 --- a/devito/finite_differences/operators.py +++ b/devito/finite_differences/operators.py @@ -12,7 +12,8 @@ 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) @@ -20,9 +21,9 @@ def div(func, shift=None, order=None, method='FD'): 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'): diff --git a/devito/finite_differences/tools.py b/devito/finite_differences/tools.py index 14910aee90..0aa56f316b 100644 --- a/devito/finite_differences/tools.py +++ b/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 diff --git a/devito/types/dense.py b/devito/types/dense.py index 37d41aba3d..74baeab3d0 100644 --- a/devito/types/dense.py +++ b/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 diff --git a/devito/types/tensor.py b/devito/types/tensor.py index d7e9999a2f..0ca08b44b1 100644 --- a/devito/types/tensor.py +++ b/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)