Document that __setitem__ leaves ghost regions unchanged

psydac/linalg/block.py

@@ -374,13 +374,27 @@ def __getitem__(self, key):
 
     # ...
     def __setitem__(self, key, value):
+        """
+        Replace the block at the given position.
+
+        This does not change the flag `ghost_regions_in_sync` of the block
+        vector, which is stored independently of the flags of its blocks.
+        """
         assert value.space == self.space[key]
         assert isinstance(value, Vector)
         self._blocks[key] = value
 
     # ...
     @property
     def ghost_regions_in_sync(self):
+        """
+        True if the ghost regions of all blocks are known to be up to date.
+
+        This flag decides whether the collective method `update_ghost_regions`
+        is called, hence it must have the same value on all processes. It is
+        stored independently of the flags of the blocks, and setting it also
+        sets the flags of all blocks. It is not changed by `__setitem__`.
+        """
         return self._sync
 
     # ...

psydac/linalg/stencil.py

@@ -712,12 +712,29 @@ def __getitem__(self, key):
 
     # ...
     def __setitem__(self, key, value):
+        """
+        Write into the data array at the given (global) indices.
+
+        This updates neither the ghost regions nor the flag
+        `ghost_regions_in_sync`, because writes are often performed on a
+        subset of the processes only, while updating the ghost regions is a
+        collective operation. If needed, call `update_ghost_regions`
+        collectively afterwards.
+        """
         index = self._getindex(key)
         self._data[index] = value
 
     # ...
     @property
     def ghost_regions_in_sync(self):
+        """
+        True if the ghost regions are known to be up to date.
+
+        This flag decides whether the collective method `update_ghost_regions`
+        is called, hence it must have the same value on all processes. It is
+        not changed by `__setitem__`: after writing the data directly, call
+        `update_ghost_regions` collectively if the ghost regions are needed.
+        """
         return self._sync
 
     # ...
@@ -1216,6 +1233,15 @@ def __getitem__(self, key):
 
     # ...
     def __setitem__(self, key, value):
+        """
+        Write into the data array at the given (global) indices.
+
+        This updates neither the ghost regions nor the flag
+        `ghost_regions_in_sync`, because writes are often performed on a
+        subset of the processes only, while updating the ghost regions is a
+        collective operation. If needed, call `update_ghost_regions`
+        collectively afterwards.
+        """
         index = self._getindex( key )
         self._data[index] = value
 
@@ -1682,6 +1708,14 @@ def _tocoo_parallel_with_pads(self , order='C'):
     # ...
     @property
     def ghost_regions_in_sync(self):
+        """
+        True if the ghost regions are known to be up to date.
+
+        This flag decides whether the collective method `update_ghost_regions`
+        is called, hence it must have the same value on all processes. It is
+        not changed by `__setitem__`: after writing the data directly, call
+        `update_ghost_regions` collectively if the ghost regions are needed.
+        """
         return self._sync
 
     # ...
@@ -2557,6 +2591,15 @@ def __getitem__(self, key):
 
     # ...
     def __setitem__(self, key, value):
+        """
+        Write into the data array at the given (global) indices.
+
+        This updates neither the ghost regions nor the flag
+        `ghost_regions_in_sync`, because writes are often performed on a
+        subset of the processes only, while updating the ghost regions is a
+        collective operation. If needed, call `update_ghost_regions`
+        collectively afterwards.
+        """
         index = self._getindex( key )
         self._data[index] = value
 
@@ -2664,6 +2707,14 @@ def _tocoo_no_pads(self):
     # ...
     @property
     def ghost_regions_in_sync(self):
+        """
+        True if the ghost regions are known to be up to date.
+
+        This flag decides whether the collective method `update_ghost_regions`
+        is called, hence it must have the same value on all processes. It is
+        not changed by `__setitem__`: after writing the data directly, call
+        `update_ghost_regions` collectively if the ghost regions are needed.
+        """
         return self._sync
 
     # ...