[yguclu]

Document how __setitem__ interacts with the ghost regions of distributed vectors and matrices (see #613).

Writing through __setitem__ updates neither the ghost regions nor the flag ghost_regions_in_sync. This is intentional: the flag decides whether the collective method update_ghost_regions is called, hence it must have the same value on all processes, while writes are often performed on a subset of the processes only (e.g. in apply_essential_bc). Resetting the flag automatically could therefore make some processes enter the collective update alone, and hang. Issue #613 was closed as not planned for this reason.

• Add docstrings to __setitem__ and to the property ghost_regions_in_sync of StencilVector, StencilMatrix, and StencilInterfaceMatrix: after writing the data directly, call update_ghost_regions collectively if the ghost regions are needed
• Add docstrings to __setitem__ and to the property ghost_regions_in_sync of BlockVector: its flag is stored independently of the flags of its blocks, and replacing a block does not change it

No functional change.

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 0 complexity · 3 duplication

Metric	Results
Complexity	0
Duplication	3

View in Codacy

🟢 Coverage ∅ diff coverage · -0.03% coverage variation

Metric	Results
Coverage variation	✅ -0.03% coverage variation
Diff coverage	✅ ∅ diff coverage

View coverage diff in Codacy

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (e520f53)	52327	33599	64.21%
Head commit (b1af8b9)	104654 (+52327)	67162 (+33563)	64.18% (-0.03%)

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

	Coverable lines	Covered lines	Diff coverage
Pull request (#626)	0	0	∅ (not applicable)

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[FrederikSchnack]

LGTM