From 7045f504a83c13000b0e9065720c196b090fa6fe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Yaman=20G=C3=BC=C3=A7l=C3=BC?= <yaman.guclu@gmail.com>
Date: Sun, 11 Oct 2026 21:12:34 +0200
Subject: [PATCH] Document that __setitem__ leaves ghost regions and their flag
 unchanged, see #613

---
 psydac/linalg/block.py   | 14 +++++++++++
 psydac/linalg/stencil.py | 51 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 65 insertions(+)

diff --git a/psydac/linalg/block.py b/psydac/linalg/block.py
index 846535d75..6467e1d7c 100644
--- a/psydac/linalg/block.py
+++ b/psydac/linalg/block.py
@@ -374,6 +374,12 @@ 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
@@ -381,6 +387,14 @@ def __setitem__(self, 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
 
     # ...
diff --git a/psydac/linalg/stencil.py b/psydac/linalg/stencil.py
index fe3288be0..2310c18c7 100644
--- a/psydac/linalg/stencil.py
+++ b/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
 
     # ...