From 7e8e6468ab727c24b9fa4170d01b2595f50b4170 Mon Sep 17 00:00:00 2001 From: mloubout Date: Mon, 13 Nov 2023 08:43:59 -0500 Subject: [PATCH] api: docstring for diff operators --- devito/finite_differences/differentiable.py | 44 +++++++++++++++++ devito/finite_differences/operators.py | 36 ++++++++++++-- devito/types/tensor.py | 55 ++++++++++++++++++++- 3 files changed, 131 insertions(+), 4 deletions(-) diff --git a/devito/finite_differences/differentiable.py b/devito/finite_differences/differentiable.py index 3ed317048e1..d0308e2e690 100644 --- a/devito/finite_differences/differentiable.py +++ b/devito/finite_differences/differentiable.py @@ -272,6 +272,22 @@ def laplace(self): return self.laplacian() def laplacian(self, shift=None, order=None): + """ + Laplacian of the Differentiable with shifted derivatives and custom + FD order. + + Each second derivative is left-right (i.e D^T D with D the first derivative ): + `(self.dx(x0=dim+shift*dim.spacing, + fd_order=order)).dx(x0=dim-shift*dim.spacing, fd_order=order)` + + Parameters + ---------- + shift: Number, optional, default=None + Shift for the center point of the derivative in number of gridpoints + order: int, optional, default=None + Discretization order for the finite differences. + Uses `func.space_order` when not specified + """ order = order or self.space_order space_dims = [d for d in self.dimensions if d.is_Space] shift_x0 = make_shift_x0(shift, (len(space_dims),)) @@ -281,6 +297,20 @@ def laplacian(self, shift=None, order=None): for i, d in enumerate(derivs)]) def div(self, shift=None, order=None): + """ + Divergence of the input Function. + + Parameters + ---------- + func : Function or TensorFunction + Function to take the divergence of + shift: Number, optional, default=None + Shift for the center point of the derivative in number of gridpoints + order: int, optional, default=None + Discretization order for the finite differences. + Uses `func.space_order` when not specified + + """ space_dims = [d for d in self.dimensions if d.is_Space] shift_x0 = make_shift_x0(shift, (len(space_dims),)) order = order or self.space_order @@ -289,6 +319,20 @@ def div(self, shift=None, order=None): for i, d in enumerate(space_dims)]) def grad(self, shift=None, order=None): + """ + Gradient of the input Function. + + Parameters + ---------- + func : Function or TensorFunction + Function to take the gradient of + shift: Number, optional, default=None + Shift for the center point of the derivative in number of gridpoints + order: int, optional, default=None + Discretization order for the finite differences. + Uses `func.space_order` when not specified + + """ from devito.types.tensor import VectorFunction, VectorTimeFunction space_dims = [d for d in self.dimensions if d.is_Space] shift_x0 = make_shift_x0(shift, (len(space_dims),)) diff --git a/devito/finite_differences/operators.py b/devito/finite_differences/operators.py index 1bf1ad5a42b..05299fc695c 100644 --- a/devito/finite_differences/operators.py +++ b/devito/finite_differences/operators.py @@ -5,6 +5,13 @@ def div(func, shift=None, order=None): Parameters ---------- func : Function or TensorFunction + Function to take the divergence of + shift: Number, optional, default=None + Shift for the center point of the derivative in number of gridpoints + order: int, optional, default=None + Discretization order for the finite differences. + Uses `func.space_order` when not specified + """ try: return func.div(shift=shift, order=order) @@ -18,7 +25,14 @@ def grad(func, shift=None, order=None): Parameters ---------- - func : Function or VectorFunction + func : Function or TensorFunction + Function to take the gradient of + shift: Number, optional, default=None + Shift for the center point of the derivative in number of gridpoints + order: int, optional, default=None + Discretization order for the finite differences. + Uses `func.space_order` when not specified + """ try: return func.grad(shift=shift, order=order) @@ -28,11 +42,17 @@ def grad(func, shift=None, order=None): def curl(func, shift=None, order=None): """ - Curl of the input Function. + Curl of the input Function. Only supported for VectorFunction Parameters ---------- func : VectorFunction + VectorFunction to take curl of + shift: Number, optional, default=None + Shift for the center point of the derivative in number of gridpoints + order: int, optional, default=None + Discretization order for the finite differences. + Uses `func.space_order` when not specified """ try: return func.curl(shift=shift, order=order) @@ -46,7 +66,13 @@ def laplace(func, shift=None, order=None): Parameters ---------- - func : Function or TensorFunction + func : VectorFunction + VectorFunction to take laplacian of + shift: Number, optional, default=None + Shift for the center point of the derivative in number of gridpoints + order: int, optional, default=None + Discretization order for the finite differences. + Uses `func.space_order` when not specified """ try: return func.laplacian(shift=shift, order=order) @@ -61,6 +87,10 @@ def diag(func, size=None): Parameters ---------- func : Differentiable or scalar + Symbolic object to set the diagonal to + size: int, optional, default=None + size of the diagonal matrix (size x size). + Defaults to the number of spatial dimensions when unspecified """ dim = size or len(func.dimensions) dim = dim-1 if func.is_TimeDependent else dim diff --git a/devito/types/tensor.py b/devito/types/tensor.py index 3f0c3c8e4ce..f2cab51825a 100644 --- a/devito/types/tensor.py +++ b/devito/types/tensor.py @@ -195,6 +195,14 @@ def values(self): def div(self, shift=None, order=None): """ Divergence of the TensorFunction (is a VectorFunction). + + Parameters + ---------- + shift: Number, optional, default=None + Shift for the center point of the derivative in number of gridpoints + order: int, optional, default=None + Discretization order for the finite differences. + Uses `func.space_order` when not specified """ comps = [] func = vec_func(self) @@ -216,7 +224,20 @@ def laplace(self): def laplacian(self, shift=None, order=None): """ - Laplacian of the TensorFunction. + Laplacian of the TensorFunction with shifted derivatives and custom + FD order. + + Each second derivative is left-right (i.e D^T D with D the first derivative ): + `(self.dx(x0=dim+shift*dim.spacing, + fd_order=order)).dx(x0=dim-shift*dim.spacing, fd_order=order)` + + Parameters + ---------- + shift: Number, optional, default=None + Shift for the center point of the derivative in number of gridpoints + order: int, optional, default=None + Discretization order for the finite differences. + Uses `func.space_order` when not specified """ comps = [] func = vec_func(self) @@ -298,6 +319,14 @@ def __str__(self): def div(self, shift=None, order=None): """ Divergence of the VectorFunction, creates the divergence Function. + + Parameters + ---------- + shift: Number, optional, default=None + Shift for the center point of the derivative in number of gridpoints + order: int, optional, default=None + Discretization order for the finite differences. + Uses `func.space_order` when not specified """ shift_x0 = make_shift_x0(shift, (len(self.space_dimensions),)) order = order or self.space_order @@ -315,6 +344,14 @@ def laplace(self): def laplacian(self, shift=None, order=None): """ Laplacian of the VectorFunction, creates the Laplacian VectorFunction. + + Parameters + ---------- + shift: Number, optional, default=None + Shift for the center point of the derivative in number of gridpoints + order: int, optional, default=None + Discretization order for the finite differences. + Uses `func.space_order` when not specified """ func = vec_func(self) shift_x0 = make_shift_x0(shift, (len(self.space_dimensions),)) @@ -328,6 +365,14 @@ def laplacian(self, shift=None, order=None): def curl(self, shift=None, order=None): """ Gradient of the (3D) VectorFunction, creates the curl VectorFunction. + + Parameters + ---------- + shift: Number, optional, default=None + Shift for the center point of the derivative in number of gridpoints + order: int, optional, default=None + Discretization order for the finite differences. + Uses `func.space_order` when not specified """ if len(self.space_dimensions) != 3: raise AttributeError("Curl only supported for 3D VectorFunction") @@ -354,6 +399,14 @@ def curl(self, shift=None, order=None): def grad(self, shift=None, order=None): """ Gradient of the VectorFunction, creates the gradient TensorFunction. + + Parameters + ---------- + shift: Number, optional, default=None + Shift for the center point of the derivative in number of gridpoints + order: int, optional, default=None + Discretization order for the finite differences. + Uses `func.space_order` when not specified """ func = tens_func(self) ndim = len(self.space_dimensions)