data: Use single backticks in docstrings for code names

Match the single-backtick `name` convention rather than the double
``name`` form, across the distributed engine and the docstrings/comments
this branch added to data.py, decomposition.py and test_data.py.
Pre-existing double-backtick text elsewhere is left untouched.

Author: mloubout

devito/data/data.py

@@ -185,9 +185,9 @@ def _is_decomposed(self):
 
     def _scattered_exchange(self, glb_idx):
         """
-        Return an ``Exchange`` when ``glb_idx`` advanced-indexes a
+        Return an `Exchange` when `glb_idx` advanced-indexes a
         distributed axis (the "unbalanced"/scattered case, where the value is
-        rank-local and ordered by ``glb_idx``), otherwise ``None`` so the caller
+        rank-local and ordered by `glb_idx`), otherwise `None` so the caller
         falls back to the regular (basic-indexing) path.
         """
         # Imported lazily: the redistribution engine depends on `devito.mpi`,
@@ -241,7 +241,7 @@ def swapaxes(self, axis1, axis2):
         """
         Return a view of ``self`` with ``axis1`` and ``axis2`` swapped, with
         ``_decomposition`` / ``_modulo`` swapped in the same way (see
-        ``transpose``).
+        `transpose`).
         """
         axis1 = axis1 % self.ndim
         axis2 = axis2 % self.ndim
@@ -257,7 +257,7 @@ def swapaxes(self, axis1, axis2):
     def T(self):
         """
         The transposed array. Overridden so the C-level ``ndarray.T`` shortcut
-        also permutes the per-axis metadata (see ``transpose``).
+        also permutes the per-axis metadata (see `transpose`).
         """
         return self.transpose()
 
@@ -523,12 +523,12 @@ def _set_global_idx(self, val, idx, val_idx):
     def _gather(self, start=None, stop=None, step=1, rank=0):
         """
         Gather (a slice of) the distributed data into a NumPy array on a single
-        rank, returning ``None`` on the others. See the public ``data_gather``
+        rank, returning `None` on the others. See the public `data_gather`
         method of `Function`.
 
         Indexing is local (each rank already holds its induced result block);
         gathering is the explicit collect step -- every rank sends its block and
-        the result indices it owns, and ``rank`` reassembles the global array.
+        the result indices it owns, and `rank` reassembles the global array.
         """
         if not isinstance(rank, int):
             raise TypeError('rank must be passed as an integer value.')

devito/data/decomposition.py

@@ -577,7 +577,7 @@ def index_decomposition(self, idx):
         Each subdomain keeps the result positions, in index order, of the global
         indices it owns. A strided or reversed slice therefore just relabels
         which rank owns which result index -- indexing never moves data across
-        ranks. Unlike ``reshape`` (which adjusts subdomain *boundaries* and
+        ranks. Unlike `reshape` (which adjusts subdomain *boundaries* and
         is used for halos), this follows exact NumPy slicing semantics.
 
         Examples

devito/data/distributed/__init__.py

@@ -4,13 +4,13 @@
 Indexing an MPI-distributed array is treated as a redistribution between layouts.
 The engine is built as four pure layers plus a value object:
 
-* ``selection`` -- what an index expression means (serial NumPy semantics).
-* ``layout``    -- where a global coordinate physically lives.
-* ``plan``      -- the rank-to-rank routing, built without communication.
-* ``transport`` -- the sparse point-to-point exchange (NBX).
-* ``exchange``  -- ``Exchange(data, idx).get()/.put(value)``.
+* `selection` -- what an index expression means (serial NumPy semantics).
+* `layout`    -- where a global coordinate physically lives.
+* `plan`      -- the rank-to-rank routing, built without communication.
+* `transport` -- the sparse point-to-point exchange (NBX).
+* `exchange`  -- `Exchange(data, idx).get()/.put(value)`.
 
-Only ``Exchange`` is needed by ``Data``; the lower layers are independently
+Only `Exchange` is needed by `Data`; the lower layers are independently
 testable (in serial, or with toy buffers).
 """
 

devito/data/distributed/exchange.py

@@ -1,13 +1,13 @@
 """
 Exchange: the value object tying a Selection and a Layout into a reusable plan.
 
-``Exchange(data, idx)`` builds the routing for one index expression without any
-communication. ``get`` pulls ``data[idx]`` and ``put`` assigns ``data[idx] =
-value``. Because the plan is communication-free to build and independent of the
+`Exchange(data, idx)` builds the routing for one index expression without any
+communication. `get` pulls `data[idx]` and `put` assigns `data[idx] =
+value`. Because the plan is communication-free to build and independent of the
 data *values*, it can be cached and replayed across calls with the same index
 (e.g. sparse injection every timestep), so the steady state is pure
-point-to-point with no re-planning. ``cached_exchange`` provides that cache;
-``Data`` uses it so ``data[idx] = value`` is automatically plan-cached.
+point-to-point with no re-planning. `cached_exchange` provides that cache;
+`Data` uses it so `data[idx] = value` is automatically plan-cached.
 """
 
 from functools import lru_cache
@@ -25,7 +25,7 @@
 class Exchange:
 
     """
-    A reusable redistribution plan for ``data[idx]`` on distributed ``data``.
+    A reusable redistribution plan for `data[idx]` on distributed `data`.
 
     Parameters
     ----------
@@ -49,22 +49,22 @@ def __init__(self, data, idx):
         self._plan = ExchangePlan.build(self._selection, self._layout)
 
     def get(self):
-        """Return ``data[idx]`` as a NumPy array."""
+        """Return `data[idx]` as a NumPy array."""
         return self._plan.get(np.asarray(self._data))
 
     def put(self, value):
-        """Assign ``data[idx] = value``."""
+        """Assign `data[idx] = value`."""
         self._plan.put(np.asarray(self._data), value)
 
 
 class _ExchangeKey:
 
     """
-    Hashable, content-addressed key wrapping ``(data, idx)`` for plan caching.
+    Hashable, content-addressed key wrapping `(data, idx)` for plan caching.
 
     NumPy index arrays are unhashable, so the key digests their content (together
     with the decomposition and shape the plan depends on) and lets
-    ``functools.lru_cache`` own eviction. Content addressing means a freshly
+    `functools.lru_cache` own eviction. Content addressing means a freshly
     built index array with the same values still hits, and an in-place mutation
     correctly misses.
     """
@@ -89,7 +89,7 @@ def _build(key):
 
 
 def cached_exchange(data, idx):
-    """Return a (cached) ``Exchange`` for ``data[idx]``."""
+    """Return a (cached) `Exchange` for `data[idx]`."""
     return _build(_ExchangeKey(data, idx))
 
 

devito/data/distributed/layout.py

@@ -1,9 +1,9 @@
 """
 Layout layer: where a global coordinate physically lives.
 
-A ``Layout`` wraps a distributor and a per-axis decomposition and answers,
+A `Layout` wraps a distributor and a per-axis decomposition and answers,
 for any axis, "which rank owns global index g, and at what local offset". It is
-the single bridge between the layout-independent ``Selection`` and the
+the single bridge between the layout-independent `Selection` and the
 physical MPI placement, and it is what makes replicated and distributed axes
 look uniform to the planner. All maps are computed locally from replicated
 metadata; no communication happens here.
@@ -29,7 +29,7 @@ class Layout:
         Provides the communicator, topology and rank/coord maps.
     decomposition : tuple
         One entry per array axis: a Decomposition for a distributed axis, or
-        ``None`` for a replicated axis.
+        `None` for a replicated axis.
     global_shape : tuple of int
         The global array shape (full size on every axis).
     """
@@ -61,12 +61,12 @@ def axis_maps(self, axis):
         Returns
         -------
         owner : ndarray
-            ``owner[g]`` is the topology sub-rank owning global index ``g`` along
-            this axis (``-1`` if out of bounds).
+            `owner[g]` is the topology sub-rank owning global index `g` along
+            this axis (`-1` if out of bounds).
         local : ndarray
-            ``local[g]`` is the offset of ``g`` within its owner's subdomain.
+            `local[g]` is the offset of `g` within its owner's subdomain.
         sizes : ndarray
-            ``sizes[i]`` is the number of indices owned by sub-rank ``i``.
+            `sizes[i]` is the number of indices owned by sub-rank `i`.
         """
         return self._axis_maps[axis]
 
@@ -98,7 +98,7 @@ def topology_shape(self):
     def coord_to_rank(self):
         """Map a topology coordinate tuple (over distributed axes) to a flat rank.
 
-        Grid distributors expose the inverse Cartesian map via ``all_coords``;
+        Grid distributors expose the inverse Cartesian map via `all_coords`;
         single-axis distributors (e.g. sparse) lay ranks out linearly, so the
         sole sub-rank index is the flat rank.
         """

devito/data/distributed/plan.py

@@ -1,11 +1,11 @@
 """
 Plan layer: the rank-to-rank routing induced by a Selection on a Layout.
 
-``ExchangePlan`` is a value object built once (no communication) from a
-``Selection`` and a ``Layout``. It computes, for every routed element, its
+`ExchangePlan` is a value object built once (no communication) from a
+`Selection` and a `Layout`. It computes, for every routed element, its
 owner rank and owner-local offset, and arranges the result/value array as
-``(npoints, payload)`` so packing and unpacking are single NumPy fancy-index
-operations. The same plan drives ``get`` (pull) and ``put`` (push).
+`(npoints, payload)` so packing and unpacking are single NumPy fancy-index
+operations. The same plan drives `get` (pull) and `put` (push).
 
 Every axis falls in one of four quadrants and is handled uniformly:
 
@@ -35,14 +35,14 @@ class ExchangePlan:
     """
     The rank-to-rank routing induced by a Selection on a Layout.
 
-    A plan is built once, without communication, and then drives both ``get``
-    (pull ``data[idx]``) and ``put`` (assign ``data[idx] = value``). It maps
+    A plan is built once, without communication, and then drives both `get`
+    (pull `data[idx]`) and `put` (assign `data[idx] = value`). It maps
     every routed result element to its owner rank and owner-local offset, and
     splits the result axes into a "T" (transport) block over the distributed
     axes and a contiguous "payload" block over the replicated axes, so packing
     and unpacking are single NumPy fancy-index operations.
 
-    Use ``build`` to construct one; the constructor takes the already
+    Use `build` to construct one; the constructor takes the already
     computed routing tables.
 
     Parameters
@@ -52,15 +52,15 @@ class ExchangePlan:
     selection : Selection
         Normalized meaning of the index expression.
     perm : list of int
-        Permutation taking the result axes to ``(T-dims..., payload-dims...)``.
+        Permutation taking the result axes to `(T-dims..., payload-dims...)`.
     t_shape : tuple of int
         Shape of the transport block (the distributed result axes).
     payload_shape : tuple of int
         Shape of the payload block (the replicated result axes).
     owners : numpy.ndarray
-        Owner rank of each T row (``-1`` when out of bounds).
+        Owner rank of each T row (`-1` when out of bounds).
     peers : dict
-        Maps a peer rank to ``(rows, dist_lin)``: the T rows it owns and their
+        Maps a peer rank to `(rows, dist_lin)`: the T rows it owns and their
         owner-local linear offsets over the distributed axes.
     block_offsets : numpy.ndarray
         Offset of each payload element within the owner's replicated block.
@@ -91,7 +91,7 @@ def __init__(self, layout, selection, perm, t_shape, payload_shape, owners,
     @classmethod
     def build(cls, selection, layout):
         """
-        Plan the exchange for ``data[idx]``; the result serves both get and set.
+        Plan the exchange for `data[idx]`; the result serves both get and set.
 
         Parameters
         ----------
@@ -159,7 +159,7 @@ def payload_size(self):
     def _raise_on_error(self, check_dup):
         """Reach consensus on local errors and raise consistently on all ranks.
 
-        A single 1-bit ``Allreduce`` gates the (rare) error path so that every
+        A single 1-bit `Allreduce` gates the (rare) error path so that every
         rank raises together, avoiding a deadlock where one rank raises while the
         others enter the exchange. This is log-depth, not an all-to-all.
         """
@@ -187,7 +187,7 @@ def _owner_apply(self, moved, dist_lin, block_offsets):
 
     def get(self, local):
         """
-        Return ``data[idx]`` as a NumPy array by pulling from the owner ranks.
+        Return `data[idx]` as a NumPy array by pulling from the owner ranks.
 
         Parameters
         ----------
@@ -197,7 +197,7 @@ def get(self, local):
         Returns
         -------
         numpy.ndarray
-            The indexed result, in ``selection.result_shape``.
+            The indexed result, in `selection.result_shape`.
         """
         self._raise_on_error(check_dup=False)
         comm, ps = self.comm, self.payload_size
@@ -228,14 +228,14 @@ def get(self, local):
 
     def put(self, local, value):
         """
-        Assign ``data[idx] = value`` by pushing to the owner ranks.
+        Assign `data[idx] = value` by pushing to the owner ranks.
 
         Parameters
         ----------
         local : numpy.ndarray
             The caller's rank-local array (written in place).
         value : array_like
-            The value to assign, broadcast to ``selection.result_shape``.
+            The value to assign, broadcast to `selection.result_shape`.
         """
         self._raise_on_error(check_dup=True)
         rows_flat = self._value_to_rows(value, local.dtype)
@@ -314,11 +314,11 @@ def _resolve_owners(selection, layout, gcoords):
     Returns
     -------
     owners : numpy.ndarray
-        Flat owner rank per T row (``-1`` if out of bounds).
+        Flat owner rank per T row (`-1` if out of bounds).
     local : numpy.ndarray
-        Per-axis owner-local offset per T row, shaped ``(naxes, nrows)``.
+        Per-axis owner-local offset per T row, shaped `(naxes, nrows)`.
     sub : numpy.ndarray
-        Per-axis owner sub-rank per T row, shaped ``(naxes, nrows)``.
+        Per-axis owner sub-rank per T row, shaped `(naxes, nrows)`.
     """
     axes = layout.distributed_axes
     nrows = len(next(iter(gcoords.values()))) if gcoords else 0
@@ -386,7 +386,7 @@ def _group_peers(layout, owners, dist_local, sub, gcoords):
     Returns
     -------
     peers : dict
-        Maps a peer rank to ``(rows, dist_lin)``: the T rows it owns and their
+        Maps a peer rank to `(rows, dist_lin)`: the T rows it owns and their
         owner-local linear offsets over the distributed axes.
     oob_error : str or None
         Set when any row addresses an out-of-bounds global index.
@@ -425,12 +425,12 @@ def _group_peers(layout, owners, dist_local, sub, gcoords):
 def nbx_push(comm, distributed_axes, repl_total, peers, block_offsets,
              payload_size, rows_flat, local):
     """
-    Route ``rows_flat`` to the owner ranks (NBX) and scatter each received
-    payload into ``local`` at its owner-local position.
+    Route `rows_flat` to the owner ranks (NBX) and scatter each received
+    payload into `local` at its owner-local position.
 
-    This is the single push primitive behind both ``ExchangePlan.put``
-    (advanced/replicated assignment, ``payload_size`` >= 1) and the structured
-    redistribution layer (one value per point, ``payload_size`` == 1).
+    This is the single push primitive behind both `ExchangePlan.put`
+    (advanced/replicated assignment, `payload_size` >= 1) and the structured
+    redistribution layer (one value per point, `payload_size` == 1).
 
     Parameters
     ----------
@@ -441,13 +441,13 @@ def nbx_push(comm, distributed_axes, repl_total, peers, block_offsets,
     repl_total : int
         Full replicated stride (1 when there is no replicated payload).
     peers : dict
-        Maps a peer rank to ``(rows, dist_lin)`` (see ``_group_peers``).
+        Maps a peer rank to `(rows, dist_lin)` (see `_group_peers`).
     block_offsets : numpy.ndarray
         Offset of each payload element within an owner's replicated block.
     payload_size : int
         Number of payload elements per point.
     rows_flat : numpy.ndarray
-        Values to push, shaped ``(nrows, payload_size)`` in owner-grouped order.
+        Values to push, shaped `(nrows, payload_size)` in owner-grouped order.
     local : numpy.ndarray
         The owner's rank-local array (written in place).
     """
@@ -469,12 +469,12 @@ def nbx_push(comm, distributed_axes, repl_total, peers, block_offsets,
 
 
 def _encode(payload_size, block_offsets, dist_lin):
-    """Pack a request header as ``[payload_size, *block_offsets, *dist_lin]``."""
+    """Pack a request header as `[payload_size, *block_offsets, *dist_lin]`."""
     return np.concatenate(([payload_size], block_offsets, dist_lin)).astype(np.int64)
 
 
 def _decode(buf):
-    """Unpack a request header into ``(block_offsets, dist_lin)``."""
+    """Unpack a request header into `(block_offsets, dist_lin)`."""
     payload_size = int(buf[0])
     block_offsets = buf[1:1 + payload_size]
     dist_lin = buf[1 + payload_size:]