[jamesmkrieger]

(This PR incorporates Anthony's #2200)

The parallel paths in interactions.py and waterbridges.py could not be relied on. This
is the cause of the macOS CI failures that appear to move between matrix cells.

The workers could not be pickled

Each per-frame worker was a nested function. multiprocessing pickles the target of a
Process under the "spawn" start method — the default on macOS since Python 3.8 and on
Windows always — and a nested function cannot be pickled, so p.start() raised:

AttributeError: Can't pickle local object
  'calcInteractionsMultipleFrames.<locals>.analyseFrame'

The parallel path therefore only ever ran where "fork" is still the default. Six workers
move to module level and take what they closed over as arguments; the frame workers take
coordinates as a plain array rather than a Frame, which would drag its whole Trajectory
into the child.

Why it looks Python-version specific

max_proc defaults to mp.cpu_count()//2, so whether the parallel path is entered at all
depends on the machine: a two- or three-core runner gets 1 and goes serial, a four-core one
gets 2 and does not. macOS runner images differ in core count, so the same commit passes or
fails on the same matrix cell between runs. It is not a Python version boundary, and giving
CI more cores would make the failure deterministic rather than fix it.

Results came back in completion order

The interactions.py workers appended to the shared list, recording results in the order
the processes happened to finish, so the parallel path silently returned frames out of order
— six frames at max_proc=3 came back as 2, 0, 1, 3, 4, 5. Each worker now writes into its
own slot of a pre-sized list indexed by frame, which is what the waterbridges.py workers
already did; that idiom is now used in both.

A dead worker looked like an empty result

A Process reports failure only through its exitcode: the exception is raised in the child,
whose traceback goes to stderr, and a worker that writes into a shared list leaves its slot
untouched. Every parallel loop joined its processes without checking. New
prody.utilities.joinProcesses joins and raises if any died, naming how many and their exit
codes and pointing at max_proc=1 to get the exception itself in-process. All six loops use
it.

No water is an empty result, not an error

calcWaterBridges raised ValueError when the structure had no water, and
findClusterCenters raised when nothing passed the clustering filter. Neither is an error:
a structure with no water has no water bridges, and that is the answer. Raising aborted a
whole batch on one such structure — whether that batch was a script looping serially or a
parallel run over frames — and in the parallel case the two paths disagreed, since the
child's exception was swallowed and the frame came back empty anyway. Both now warn and
return empty. Every output type of calcWaterBridges — indices, atomic, info, and both the
chain and cluster methods — is a list, so an empty list is the right shape for all of them.

Relatedly, the no-trajectory exit of calcProteinInteractionsTrajectory returned
interactions_nb_traj, a local not assigned until further down the function, so it raised
UnboundLocalError rather than returning. That variable is now bound up front, exactly
where calcInteractionsMultipleFrames binds interactions_all, and returned — so both
functions answer the same way when there is nothing to iterate.

stop_frame is the last frame, inclusive

That is what calcWaterBridgesTrajectory does for a trajectory, and what interactions.py
does throughout and documents as "index of last frame to read". waterbridges.py's
multi-model branch sliced [start_frame:stop_frame] and so silently dropped the last model,
and it never resolved the -1 default there, which with the +1 would have become an empty
slice. Both parallel multi-model loops also started their counter at start_frame while the
worker adds start_frame itself, applying the offset twice — invisible only at the default
of 0.

One implementation, not two

InteractionsTrajectory.calcProteinInteractionsTrajectory had its own copy of the per-frame
loop for all seven interaction types at once, duplicating calcInteractionsMultipleFrames.
Two code paths for the same job meant each fix had to be made twice, and in practice was
not. AnthonyBogetti's insty-fix branch replaced it with one call per interaction type, which
is the better shape, so this takes that and drops the now-unused all-types worker along with
the fourteen per-type lists and the frame slicing that only fed them. Verified with a linked
DCD Trajectory at max_proc 1, 2 and 3 under both start methods: seven types, three frames
each, and the trajectory's frame index back where it started.

Tests

The guarantee comes from pinning max_proc, not from the runner. Each path gets its own
test, with max_proc given explicitly:

test	max_proc	what it guarantees
testSerialPath	1, on purpose	the reference the parallel runs are compared against; also asserts the frames actually contain hydrogen bonds, so an empty-vs-empty comparison cannot pass
testParallelPathIsTaken	2	counts Process constructions and asserts one per frame, so the test cannot quietly degrade into a second serial run and still pass
testParallelKeepsFrameOrder	2, 3, 6	catches a right result recorded against the wrong frame as well as a wrong one
testParallelPathUnderSpawn	2, under a spawn context	swaps the module's multiprocessing for get_context('spawn'), so the start method macOS and Windows actually use is exercised on Linux too
testNoWaterGivesAnEmptyResult	1, 2, 3	one empty result per frame from both paths, so they cannot drift apart again
testStopFrameIsTheLastFrame	1, 2	the inclusive bound at several values in both modules, and that -1 still means all of them
testWorkersArePicklable	n/a	no multiprocessing at all; fails the moment a worker is moved back inside its caller
TestJoinProcesses	n/a	the exit-code guard directly, with workers that exit 1 and workers that exit cleanly

testParallelPathUnderSpawn is the one that matters most: it makes this class of bug
reproducible on every runner, rather than only on a macOS cell that happens to report enough
cores. Pinning cores in CI would not have given the same coverage, since Linux would still
run under "fork".

TestInteractions.tearDownClass also removed four .npy files unconditionally, so a test
that failed before saving raised FileNotFoundError on top of its own failure — turning one
failure into a failure plus an error and burying which test was the real one, as on the macOS
runs. It now removes only what is there.

With "spawn" forced on Linux, test_insty.py goes from 12 failures plus a teardown error to
26 passed, 0 failed. Full suite: 1111 passed, with only pre-existing environmental
failures remaining.

🤖 Generated with Claude Code

[jamesmkrieger]

This fixes sporadic insty parallel bugs like those found in #2275 and #2276