Add NISAR azimuth-block splitting for parallel full-frame processing

[mgovorcin]

Adds a block-as-burst pattern so NISAR full-frame GSLCs can be processed in parallel using the existing burst pool.

For burst inputs nothing changes. For NISAR (non-burst) inputs, when input_options.azimuth_blocks > 1 the frame is split into N azimuth blocks at the dispatch layer, each block is processed as a synthetic burst through ProcessPoolExecutor, and per-block outputs are stitched by the existing stitching_bursts.run step. No changes to wrapped_phase.run or the stitcher are required.

Change Summary

• workflows/_block_split.py (new) — split_frame_into_blocks() divides the pixel grid into N azimuth blocks with a halo; _min_halo_rows() auto-computes the minimum safe overlap from half-window, similarity search radius, and stride settings.
• workflows/config/_common.py — InputOptions gains azimuth_blocks: int = 1 and halo_rows: Optional[int] = None.
• workflows/displacement.py — extracts dispatch into a testable _prepare_grouped_inputs() function; sets HDF5_USE_FILE_LOCKING=FALSE before spawning workers when multiple processes share the same HDF5 files (prevents hangs on NFS/Lustre).
• workflows/_utils.py — _create_burst_cfg accepts an optional bounds parameter to set output_options.bounds per block.

Typical config for a 4-block run:

input_options:
  azimuth_blocks: 4
worker_settings:
  n_parallel_bursts: 4
  threads_per_worker: 2

CLAUDE NOTES

└── Process #k (one per active "burst" / NISAR block)
    │
    ├── ThreadPoolExecutor (size = workers_per_burst = n_parallel_bursts // active_bursts)
    │   └── threads doing GDAL/HDF5 read-ahead inside EagerLoader
    │
    └── Main thread: per-output-block phase-linking
        ├── JAX/XLA host pool (default = os.cpu_count(), can cap via XLA_FLAGS)
        │   └── parallelizes vmap'd ops across pixels
        └── BLAS via OMP_NUM_THREADS = threads_per_worker
            └── multi-threads eigh, solve, matmul inside JAX kernels

Key insight: n_parallel_bursts is dual-purpose. It's the outer pool size AND a budget that gets re-allocated to inner I/O workers when there are fewer "bursts" than pool slots.

n_parallel_bursts = 8, with N bursts available:
N = 1 (FULL) → 1 active process × 8 inner I/O threads
N = 4 → 4 active processes × 2 inner I/O threads each
N = 8 (BLOCKED) → 8 active processes × 1 inner I/O thread each

FULL vs BLOCKED

Aspect	FULL (azimuth_blocks=1)	BLOCKED (azimuth_blocks=N)
Processes	1	N (8 typical)
GIL	Locked to 1 interpreter	Escaped — N interpreters
JAX kernels	Parallelize across pixels via vmap (within 1 block)	Same per block, run N in parallel across blocks
Python control flow	Strictly serial sweep through frame	N serial sweeps in parallel
HDF5 reads	1 stream	N concurrent streams
JIT compile	Once, ~10–30 s	N times in parallel, ~30 s wall
Working set	Full frame in 1 process	~1/N of frame in each process

The speedup mechanism is N copies of single-threaded work running in parallel.

Each worker still uses ~1 core; you just have N of them running simultaneously on different rows.

---

Per-Knob Impact

n_parallel_bursts

• Bigger = more outer pool slots (capped by available bursts)
• For NISAR: this is the number of blocks running in parallel
• Set equal to azimuth_blocks for maximum block parallelism
• Typical sweet spot: both at 8

---

threads_per_worker

Sets:

• OMP_NUM_THREADS
• MKL_NUM_THREADS

Controls BLAS threads inside JAX kernels:

• eigh
• solve
• matmul

Separate from JAX/XLA’s own thread pool.

Typical values:

• 2 → reasonable default
• 1 → if CPU constrained
• 4+ → can help in FULL mode where one process can use more parallelism

---

JAX / XLA

JAX’s XLA backend maintains its own thread pool, sized by default to:

os.cpu_count()

Local benchmark full frame vs blocked results

displacement.run end-to-end through PS+PL+stitch benchmark run with taskset -c 0-33

GSLCs : 7 (Track 042 Frame 070 Descending orbit)
half_window : 5
num_blocks : 8
n_parallel_bursts : 8 (both modes)
threads_per_worker : 2 (both modes)
block_shape: 2048x2048 (both modes)
active threads FULL : 2
active threads BLK : 16

FULL wall = 10667.3s (177.79 min)
BLOCKED wall = 2411.2s ( 40.19 min)
SPEEDUP (BLOCKED vs FULL) : 4.42×

Checklist

• The pull request title is a good summary of the changes - it will be used in the changelog
• Unit tests for the changes exist
• Tests pass on CI
• Documentation reflects the changes where applicable
• My PR is ready to review