ENH: reproducible Monte Carlo via per-simulation-index seeding

[thc1006]

Pull request type

• Code changes (bugfix, features)

Draft / RFC. I'm opening this to make the design in #1053 concrete and get your call on the open questions below before polishing it.

Current behavior

MonteCarlo.simulate() seeds the stochastic models per worker in parallel mode (from a fresh, unseeded np.random.SeedSequence().spawn(n_workers)) and once at construction in serial mode. So the sampled inputs depend on the execution mode and the number of workers, and parallel runs aren't reproducible run to run. This is #1053.

New behavior

Adds a keyword-only random_seed to simulate(). From that root I spawn one child seed per simulation index and reseed the models from child_seeds[i] before simulation i. SeedSequence.spawn is prefix-stable, so index i maps to the same seed regardless of which worker runs it. The sampled inputs come out identical across serial, parallel(2) and parallel(N), and reproducible from the seed.

The design follows Scientific-Python SPEC 7 (a per-call keyword-only seed, normalized to accept an int, a SeedSequence, or a Generator, with None = fresh entropy so existing behavior is unchanged unless you pass a seed) and NumPy's documented parallel idiom (SeedSequence(root).spawn(n) then default_rng(child)).

tests/unit/simulation/test_monte_carlo_determinism.py covers it: serial reproducibility, serial == parallel(2) == parallel(4), and the None-seed path. Flight is stubbed, so it's a slow input-sampling test.

Open questions (why this is a draft)

1. Name: I used random_seed for continuity with the Stochastic* seed. SPEC 7's direction is rng (SciPy 1.15 renamed seed to rng; sklearn is weighing it in #29315). I can switch to rng if you'd rather be forward-looking.
2. Where it lives: on simulate() (per run) versus also a stored default on MonteCarlo.__init__ (hybrid). I went with simulate() only, the minimal SPEC-7 form.
3. Default: None = fresh entropy (backward-compatible, not reproducible). A competition or regression context might want a reproducible default instead.
4. Decorrelation: I split each index seed three ways so env/rocket/flight get independent streams (today they share one seed). I can drop it to keep the change minimal.
5. Known gap (from Monte Carlo results aren't reproducible across serial and parallel runs (seeding is per-worker, not per-simulation) #1053): list-valued stochastic attributes are sampled with the stdlib random.choice (an unseeded global), so a model with a multi-element thrust_source isn't fully seed-controlled yet. The test uses a single-thrust_source rocket to sidestep it; a full fix would seed the stdlib random per index too.

Breaking change

• Yes

The exact numbers a seed produces change (per-index seeding, the env/rocket/flight decorrelation, and the serial index now counting from 0 to match parallel), so stored Monte Carlo baselines such as test_monte_carlo_simulate regenerate. There's no API break for users who don't pin exact samples, and random_seed is opt-in.

One more heads-up: Python 3.14 flipped the Linux multiprocessing default from fork to forkserver, so workers no longer inherit memory and the seed objects crossing the process boundary must be picklable. SeedSequence is, and the test passes under fork.

Closes #1053

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[codecov]

Codecov Report

❌ Patch coverage is 85.18519% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.31%. Comparing base (7e37cb0) to head (0d37ed6).
⚠️ Report is 9 commits behind head on develop.

Files with missing lines	Patch %	Lines
rocketpy/simulation/monte_carlo.py	85.18%	4 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1054      +/-   ##
===========================================
+ Coverage    81.75%   82.31%   +0.55%     
===========================================
  Files          119      119              
  Lines        15192    15212      +20     
===========================================
+ Hits         12420    12521     +101     
+ Misses        2772     2691      -81     

☔ 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.

[thc1006]

Pushed 0d37ed6 to cover the seeding code that the earlier tests only reached through a full (slow) Monte Carlo run.

• New unit tests in tests/unit/simulation/test_monte_carlo_determinism.py drive __root_seed_sequence and __seed_simulation directly: every supported random_seed type normalizes to the same root stream, None draws fresh entropy, an existing SeedSequence/Generator/BitGenerator is reused rather than copied, and each child seed splits three ways so environment, rocket and flight get independent streams.
• The end-to-end simulate reproducibility tests moved to tests/integration/ next to test_monte_carlo_simulate. The serial run is in the normal suite now; only the fork-based worker-invariance test stays slow, and it imports multiprocess lazily the way the library does.

That takes the patch from 21 uncovered lines down to 4, all in the parallel branch. I looked into whether it is worth covering those too, and I do not think it is:

• Three of them (__run_in_parallel's dispatch, the child-seed spawn, and the worker loop) run in the main process. The slow worker-invariance test already exercises them; the coverage jobs just do not pass --runslow.
• The fourth, the __seed_simulation call inside __sim_producer, only runs inside a forked worker, and coverage.py does not instrument subprocesses unless the project sets concurrency = multiprocessing. So no test can count that line without a repo-wide coverage change.

So un-slowing the parallel test would recover at most the three main-process lines and still not the subprocess one, at the cost of forking workers in the default suite. I kept it slow to match the other Monte Carlo multiprocessing tests. Glad to set up multiprocessing coverage separately if you want the parallel path counted, but that felt out of scope for this PR.

[phmbressan]

The implementation is very clear and throughout, nice work.

The explanation on the concepts behind per index seeding (both in the issue and PR description) were rather helpful. I agree having reproducible results was an issue with the parallel per worker seeding.

Regarding the decisions on parameter naming, I agree with most of the decisions taken here. Moreover, the rng attribute is well docstringed, so it shouldn't be a matter of confusion to the user.

@MateusStano could you give your two cents on the changes here before we proceed with a merge?

[phmbressan]

Could you double check if after running this test, no files are left dangling on the test file system. If that is the case, using a try-finally block to remove those (as done in a few other MonteCarlo tests) is an option.

[thc1006]

Thanks for the review. On the dangling files: I checked, and nothing gets left behind. The test passes filename=tmp_path / tag into MonteCarlo, so the .inputs.txt, .outputs.txt and .errors.txt all land under pytest's per-test tmp_path and get cleaned up with it. I reran it and confirmed the repo and working directory stay clean, so there's nothing here for a try/finally to remove.

The other MonteCarlo tests need that cleanup because their fixture uses a fixed filename="monte_carlo_test", which writes into the cwd. This one keeps everything inside tmp_path instead. I'm happy to match the try/finally style if you'd prefer consistency across the file, but the tmp_path route seemed cleaner to me. Your call.