BUG: give each StochasticRocket component its own random stream

[thc1006]

41 lines of this are production code: a seeding helper in tools.py and the reset in StochasticRocket. The other 340 are tests and a section of user documentation.

Second of the split, after #1169. It does not depend on that one and applies to develop as it stands, so the two can be read in either order; #1169 is the smaller of them if only one gets a look. Whichever lands first, the other rebases onto it, and the two have been merged into a throwaway tree and run there.

Problem

Two things, both measurable on develop today.

StochasticRocket._set_stochastic hands one seed to the rocket body and to every nested component alike, so two components built from the same spec draw the same values. Two parachutes, both cd_s=0.1, lag=0.2, one reseed:

develop    (10.008249, 1.637246)    (10.008249, 1.637246)
this PR    ( 9.808764, 1.535586)    (10.227746, 1.195682)

A study of a main and a drogue was a study of one chute counted twice.

Air brakes are not in the reseed at all. They are built and sampled in create_object, and _set_stochastic never reaches them, so their values come from wherever the generator was left rather than from the seed. One seed asked three times, deployment_level=(0.5, 0.1):

develop    0.683250    0.586075    0.487737
this PR    0.545481    0.545481    0.545481

Invariant established by this PR

Every time a rocket is reset, each distinct nested stochastic model attached to it at that moment is reseeded from its own child of its collection's root, so two with the same spec are no longer made to consume the same draws, and one seed still reproduces the rocket. Independent streams can still land on equal values; what goes away is being forced to.

The reset is what builds the tree. A rocket resets itself once while being constructed, with no components attached yet, so anything added afterwards keeps the generator it was built with until something resets it again. Resetting the rocket explicitly is what does that today: a serial MonteCarlo run never resets, and a parallel one hands the model a SeedSequence where an integer is wanted, so it stops before the tree is built. Per-simulation reset from an integer seed is #1054.

Read that as the nested models' own parameters. A component's position is validated by the rocket and still belongs to the rocket's generator, which this PR does not change.

Changes

• give each collection a root of its own, spawned from the run's seed, and each component its own child of that root;
• bring air brakes into the reseed;
• name the collections once, in _POSITIONED_COLLECTIONS and _PLAIN_COLLECTIONS, and compare them with what create_object iterates, because the collection no fixture populates is the one that gets missed;
• add rocketpy.tools._seed_sequence_to_int, which turns a child into the plain int that numpy.random.default_rng and the stdlib random.Random both accept;
• say in docs/user/stochastic.rst how a rocket's components are seeded, which nothing there covered before or after.

Non-goals

• no MonteCarlo API changes. The parallel worker still hands each model a SeedSequence, while _sampler_seed rebuilds SeedSequence(entropy=seed) and wants an int or a sequence of ints. That mismatch predates this PR and ENH: reproducible Monte Carlo via per-simulation-index seeding #1054 is where it gets fixed, by converting the environment, rocket and flight children to 128-bit ints. This PR does not make the live parallel path work on its own;
• no worker lifecycle, append or checkpoint changes;
• no StochasticModel changes, so there is no overlap with BUG: keep stochastic nominal values stable across reseeds #1169;
• no change to how an eccentricity is declared or drawn, which BUG: draw the eccentricities again, whichever way they were added #1167 and BUG: draw each declared eccentricity once per simulation #1168 settled;
• nothing about a stochastic wrapper stored in two places at once, or shared between two rockets. A stream belongs to one wrapper, which the documentation now says, and enforcing it is BUG: one stochastic component wrapper can be stored on a rocket twice #1172.

Breaking change

Yes, for anything with nested components.

Every component's sampled values move, which is the point: they were correlated with each other before. The rocket body is not affected. It keeps the seed as it was given, so stochastic_calisto under seed 42 still reads mass=14.906007947 and radius=0.063501935, the same as develop.

Within a collection, a component's stream is addressed by its position in that collection, so inserting one ahead of another still moves the later ones. Collections do not move each other.

Verification

pytest tests/unit/stochastic/test_stochastic_rocket_seeding.py    10 passed
pytest tests/unit                                               2171 passed
pytest rocketpy --doctest-modules                                 48 passed
pytest tests/integration                                         154 passed
pytest tests/acceptance                                           18 passed
ruff check .  /  ruff format --check .                           clean
pylint rocketpy/ tests/ docs/                                 10.00/10, exit 0

The four tests/unit/test_sensitivity.py failures on this machine are a missing statsmodels, and they fail the same way on an unmodified develop.

On develop at 4263fa95 the new file is six red and three green. The three that survive are meant to: a single parachute already reproduces there, the body already keeps the seed it was given, and adding a surface already leaves the other collections alone, because on develop there is nothing to move them apart in the first place.

Each mechanism is pinned by a mutation, and each leaves a control standing:

undone	goes red	still passes
every component gets the root seed again	the two correlation tests	the air brake test, the source scan
air_brakes dropped from the reseed	the air brake test, the source scan	the two correlation tests
one root shared by every collection	the collection-isolation test	the rest
a collection declared that create_object never uses	the source scan	the rest
an entry reseeded twice	the exact-once count	the rest
the body moved back onto a spawned child	the body-seed test	the rest
_seed_sequence_to_int keeps only the first word	test_seed_sequence_to_int_keeps_the_full_width	all the seeding tests

That last row is why the helper has a test of its own. Collapsing it to 32 bits still hands every component a different number, so every seeding test stays green over a change that puts two streams back together near 2**16 of them.

Together with #1169

Both touch the stochastic package, so they are merged into a throwaway tree on develop and run there rather than trusted separately: pylint exit 0, ruff clean, the unit suite, doctests, integration and acceptance. The mutations that undo either change still fail their own tests in that tree, and stochastic_calisto under seed 42 still reads mass=14.906007947. Whichever of the two lands first, the other is rebased onto it and the count is taken again there rather than carried over from here.

Extracted from

#1054, second of the split. The first is #1169.

The one thing deliberately left behind is that branch's __apply_eccentricity_specs, since #1167 and #1168 replaced it on develop with something better.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.61%. Comparing base (4263fa9) to head (72be160).

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1170      +/-   ##
===========================================
+ Coverage    84.57%   84.61%   +0.03%     
===========================================
  Files          131      131              
  Lines        17527    17539      +12     
===========================================
+ Hits         14824    14841      +17     
+ Misses        2703     2698       -5     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.