From 26e7ad07ad92d7733bb7e9c89191b1601caf779f Mon Sep 17 00:00:00 2001 From: ZoeLeibowitz Date: Mon, 30 Oct 2023 12:04:19 +0000 Subject: [PATCH] misc: Edit docstrings and README --- README.md | 2 +- devito/arch/compiler.py | 4 +-- devito/builtins/arithmetic.py | 4 +-- devito/finite_differences/derivative.py | 8 +++--- devito/types/constant.py | 3 +-- devito/types/dense.py | 14 +++++----- devito/types/dimension.py | 2 +- devito/types/equation.py | 2 +- devito/types/grid.py | 3 +-- devito/types/sparse.py | 36 +++++++++++-------------- devito/types/tensor.py | 15 +++++------ 11 files changed, 41 insertions(+), 52 deletions(-) diff --git a/README.md b/README.md index 21725db8d18..eae23291495 100644 --- a/README.md +++ b/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 diff --git a/devito/arch/compiler.py b/devito/arch/compiler.py index 1c9e0f76afd..51f7e1fba6b 100644 --- a/devito/arch/compiler.py +++ b/devito/arch/compiler.py @@ -164,9 +164,9 @@ def __init__(self): 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, default=False - If True, JIT compile using a C++ compiler. Defaults to False. + If True, JIT compile using a C++ compiler. mpi : bool, optional, default=False - If True, JIT compile using an MPI compiler. Defaults to False. + If True, JIT compile using an MPI compiler. platform : Platform, optional The target Platform on which the JIT compiler will be used. """ diff --git a/devito/builtins/arithmetic.py b/devito/builtins/arithmetic.py index 48df46e5aea..bb0e31806d4 100644 --- a/devito/builtins/arithmetic.py +++ b/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 = {} diff --git a/devito/finite_differences/derivative.py b/devito/finite_differences/derivative.py index 42e6847838c..09c8c836384 100644 --- a/devito/finite_differences/derivative.py +++ b/devito/finite_differences/derivative.py @@ -28,15 +28,15 @@ class Derivative(sympy.Derivative, Differentiable): 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. + the resulting stencil. deriv_order: int or tuple of int, optional, default=1 - Derivative order. Defaults to 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``. + 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 diff --git a/devito/types/constant.py b/devito/types/constant.py index a94c798a93e..2874861c109 100644 --- a/devito/types/constant.py +++ b/devito/types/constant.py @@ -19,8 +19,7 @@ class Constant(DataSymbol, ArgProvider): name : str Name of the symbol. dtype : data-type, optional, default=np.float32 - Any object that can be interpreted as a numpy data type. Defaults - to ``np.float32``. + Any object that can be interpreted as a numpy data type. Examples -------- diff --git a/devito/types/dense.py b/devito/types/dense.py index d3ebf524821..ebe5ec17048 100644 --- a/devito/types/dense.py +++ b/devito/types/dense.py @@ -893,7 +893,7 @@ class Function(DiscreteFunction): provided, shape and dimensions must be given. For MPI execution, a Grid is compulsory. space_order : int or 3-tuple of ints, optional, default=1 - Discretisation order for space derivatives. Defaults to 1. ``space_order`` also + 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 @@ -906,8 +906,7 @@ class Function(DiscreteFunction): dimensions : tuple of Dimension, optional Dimensions associated with the object. Only necessary if ``grid`` isn't given. dtype : data-type, optional, default=np.float32 - Any object that can be interpreted as a numpy data type. Defaults - to ``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, default=None @@ -1217,7 +1216,7 @@ class TimeFunction(Function): provided, shape and dimensions must be given. For MPI execution, a Grid is compulsory. space_order : int or 3-tuple of ints, optional, default=1 - Discretisation order for space derivatives. Defaults to 1. ``space_order`` also + 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 @@ -1226,14 +1225,13 @@ class TimeFunction(Function): order (``o``) as well as the number of points on the left (``lp``) and right (``rp``) sides of a generic point of interest. time_order : int, optional, default=1 - Discretization order for time derivatives. Defaults to 1. + Discretisation order for time derivatives. shape : tuple of ints, optional 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, default=np.float32 - Any object that can be interpreted as a numpy data type. Defaults - to `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 @@ -1246,7 +1244,7 @@ class TimeFunction(Function): avoid using an alternating buffer), an explicit value for ``save`` ( an integer) must be provided. time_dim : Dimension, optional, default=grid.time_dim - TimeDimension to be used in the TimeFunction. Defaults to ``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, default=None diff --git a/devito/types/dimension.py b/devito/types/dimension.py index 20ecbc10067..69a204f9e98 100644 --- a/devito/types/dimension.py +++ b/devito/types/dimension.py @@ -784,7 +784,7 @@ class ConditionalDimension(DerivedDimension): 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 -------- diff --git a/devito/types/equation.py b/devito/types/equation.py index 9c3eea9d029..5e7425c9427 100644 --- a/devito/types/equation.py +++ b/devito/types/equation.py @@ -26,7 +26,7 @@ class Eq(sympy.Eq, Evaluable): lhs : Function or SparseFunction The left-hand side. rhs : expr-like, optional, default=0 - The right-hand side. Defaults to 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. diff --git a/devito/types/grid.py b/devito/types/grid.py index 4f25c5b10f3..0fb24365189 100644 --- a/devito/types/grid.py +++ b/devito/types/grid.py @@ -79,10 +79,9 @@ class Grid(CartesianDiscretization, ArgProvider): 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``. diff --git a/devito/types/sparse.py b/devito/types/sparse.py index 34254e6a153..35356ca6c8c 100644 --- a/devito/types/sparse.py +++ b/devito/types/sparse.py @@ -718,15 +718,14 @@ class SparseFunction(AbstractSparseFunction): coordinates : np.ndarray, optional The coordinates of each sparse point. space_order : int, optional, default=0 - Discretisation order for space derivatives. Defaults to 0. + Discretisation order for space derivatives. shape : tuple of ints, optional, default=(npoint,) - Shape of the object. Defaults to ``(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, default=np.float32 - Any object that can be interpreted as a numpy data type. Defaults - to ``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 @@ -837,17 +836,16 @@ class SparseTimeFunction(AbstractSparseTimeFunction, SparseFunction): coordinates : np.ndarray, optional The coordinates of each sparse point. space_order : int, optional, default=0 - Discretisation order for space derivatives. Defaults to 0. + Discretisation order for space derivatives. time_order : int, optional, default=1 - Discretisation order for time derivatives. Defaults to 1. + Discretisation order for time derivatives. shape : tuple of ints, optional, default=(nt, npoint) - Shape of the object. Defaults to ``(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, default=np.float32 - Any object that can be interpreted as a numpy data type. Defaults - to ``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 @@ -986,15 +984,14 @@ class PrecomputedSparseFunction(AbstractSparseFunction): potentially 216). Must be a three-dimensional array of shape `(npoint, grid.ndim, r)`. space_order : int, optional, default=0 - Discretisation order for space derivatives. Defaults to 0. + Discretisation order for space derivatives. shape : tuple of ints, optional, default=(npoint,) - Shape of the object. Defaults to `(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, dtype=np.float32 - 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 @@ -1151,17 +1148,16 @@ class PrecomputedSparseTimeFunction(AbstractSparseTimeFunction, potentially 216). Must be a three-dimensional array of shape `(npoint, grid.ndim, r)`. space_order : int, optional, default=0 - Discretisation order for space derivatives. Defaults to 0. + Discretisation order for space derivatives. time_order : int, optional, default=1 - Discretisation order for time derivatives. Default to 1. + Discretisation order for time derivatives. shape : tuple of ints, optional, default=(npoint,) - Shape of the object. Defaults to `(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, dtype=np.float32 - 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, default=None Data initializer. If a callable is provided, data is allocated lazily. allocator : MemoryAllocator, optional diff --git a/devito/types/tensor.py b/devito/types/tensor.py index 00fed1481d4..a4019c4b85c 100644 --- a/devito/types/tensor.py +++ b/devito/types/tensor.py @@ -30,7 +30,7 @@ class TensorFunction(AbstractTensor): provided, shape and dimensions must be given. For MPI execution, a Grid is compulsory. space_order : int or 3-tuple of ints, optional, default=1 - Discretisation order for space derivatives. Defaults to 1. ``space_order`` also + 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 @@ -43,10 +43,10 @@ class TensorFunction(AbstractTensor): dimensions : tuple of Dimension, optional Dimensions associated with the object. Only necessary if ``grid`` isn't given. dtype : data-type, optional, default=np.float32 - Any object that can be interpreted as a numpy data type. Defaults - to ``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 @@ -58,12 +58,9 @@ class TensorFunction(AbstractTensor): Allocate extra grid points to maximize data access alignment. When a tuple of ints, one int per Dimension should be provided. symmetric : bool, optional, default=True - Whether the tensor is symmetric or not. Defaults to True. + Whether the tensor is symmetric or not. diagonal : Bool, optional, default=False - 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. + Whether the tensor is diagonal or not. """ _is_TimeDependent = False