Skip to content

Commit

Permalink
api: docstring for diff operators
Browse files Browse the repository at this point in the history
  • Loading branch information
@mloubout
mloubout committed Nov 13, 2023
1 parent afeb337 commit 7e8e646
Show file tree
Hide file tree
Showing 3 changed files with 131 additions and 4 deletions.
44 changes: 44 additions & 0 deletions devito/finite_differences/differentiable.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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),))
Expand All @@ -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
Expand All @@ -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),))
Expand Down
36 changes: 33 additions & 3 deletions devito/finite_differences/operators.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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)
Expand All @@ -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)
Expand All @@ -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)
Expand All @@ -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
Expand Down
55 changes: 54 additions & 1 deletion devito/types/tensor.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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)
Expand Down Expand Up @@ -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
Expand All @@ -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),))
Expand All @@ -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")
Expand All @@ -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)
Expand Down

0 comments on commit 7e8e646

Please sign in to comment.