uw.selective_ranks(r) runs its body on every rank; the docstring and parallel-computing.md show the bare form as correct #837

selective_ranks is a generator context manager: it yields True on the selected ranks and False on the others, and the with body runs on every rank. Only the with uw.selective_ranks(0) as run_here: if run_here: form restricts execution.

The documentation shows the bare form as the correct one:

• the selective_ranks docstring example in src/underworld3/mpi.py (with uw.mpi.selective_ranks(0): ... plt.savefig(...));
• docs/advanced/parallel-computing.md, which also shows the right form elsewhere (lines ~150-168):
  • the "RIGHT - only rank 0" example (~line 363);
  • the migration table row "Serial code (viz, I/O) | with uw.selective_ranks(ranks):" (~424);
  • the RankGroups example (~452);
  • the migration checklist "Replace if uw.mpi.rank == 0: for visualization with with uw.selective_ranks(0):" (~506);
  • the summary "Use with uw.selective_ranks(ranks): for serial operations" (~537).

Observed. A campaign driver followed the docstring and wrote its JSON results with the bare form at np 16. Every rank wrote the same file, and 2 of 139 result files were corrupted (trailing duplicate characters).

Fix options.

1. Docs only: make every example with uw.selective_ranks(r) as run_here: / if run_here:, and say in the docstring that the body runs on all ranks.
2. API: make the bare form safe as well, either by a callable that returns a bool or by skipping the body, as some libraries do with a sentinel exception.

No library source uses the bare form (git grep on src/); the problem is in the documentation and in user code that copies it.

Underworld development team with AI support from Claude Code